Skip to main content

Adding random variation

Although you have built a well-functioning project, the variation in the output text is entirely data-driven: as the data varies, so does the output text.

There are limitations to relying only on data-driven variation, which you can see by previewing the Main output text for each row. The first paragraphs are very similar; this is because the data tends to be similar in each case. The second paragraphs are more varied because the underlying data is more varied.

To make your output text more interesting, you will now add some random variation to your script.

Adding lexical random variation

To begin adding random variation, we’ll work with the first sentence in the first paragraph.

  1. Navigate to your StateOrTerritory script.

    ARVT1.png

    In this tutorial, we’ll focus just on the first sentence, but random variation can be applied to every element of a narrative. To make it easier to see what’s going on, we’ll use a new script just for this sentence.

  2. Create a new script called StateStatistics.

  3. Copy the first sentence of the StateOrTerritory script and paste it into the new StateStatistics script.

  4. Return to the StateOrTerritory script, select the first sentence, then click Insert Script > StateStatistics. This replaces the first sentence with a call to the StateStatistics script.

    ARVT2.png

    Tip

    Assuming your StateOrTerritory script looks the same as above, there shouldn't be a period (full stop) at the end of the text in your StateStatistics script. If there is, it will produce an unwanted extra period in the output text.

  5. Preview your Main script to verify that the generated text has not changed.

    Okay, let's start with the simplest possible random variation, where different words are randomly chosen. In your current text, the increase or decrease in population is simply indicated by using the words up and down. But, of course, there are other words and phrases that can express increases and decreases. As before, you’ll use the current script as a scratch pad to build the components you want to use.

  6. Return to the StateStatistics script and add some variants for up and down on separate lines, with vertical bars between the alternatives in each case:

    up | an increase of | a rise of

    down | a decrease of | a drop of

    ARVT3.png

    Important

    When adding random lexical variation, always be careful to choose alternatives that work in the same context.

  7. Select the line of up alternatives.

  8. Click Insert Function > language > chooseAtRandom. This will open the Function Builder dialog.

    The three up alternatives have been automatically inserted into the parameter fields:

    ARVT4.png

  9. Click Save to insert the function.

  10. Repeat steps 7-9 for the down options. When done, your StateStatistics script should look like this:

    ARVT5.png

    Note

    When the editor is in Marked Up View, calls to the chooseAtRandom function are underlined in orange but do not display the function name. Instead, they display the alternatives separated by vertical bars.

    You now have two component variations for use in the host sentence. Which set of variations is chosen will be determined in the same way that the original up versus down choice was made, so there are two different ways of progressing.

    The first way is to build a new conditional expression that has the same conditions as the original one, but this time use the chooseAtRandom calls as its results. The second way is to edit the original conditional statement, replacing the current contents of its RESULT fields with your newly built chooseAtRandom function calls. Let's use the second method.

  11. Select the first chooseAtRandom call (the up alternatives) and copy it.

  12. Double-click the original conditional to open the Conditional Builder dialog.

    ARVT6.png

  13. Click in the RESULT field for Case 1, delete up, and paste the copied chooseAtRandom function call.

  14. Click Build to return to your script, copy the second chooseAtRandom function call. (the down alternatives).

  15. Double-click on the conditional to open the Conditional Builder dialog.

  16. Click in the RESULT field for Case 2, delete down, and paste the copied chooseAtRandom function call.

    ARVT7.png

  17. Leave the DEFAULT RESULT field unchanged. Since this case (zero change in the population) is very unlikely to occur, there is little value in adding random variation here.

  18. Click Build.

  19. Delete the two calls to the chooseAtRandom function. Your StateStatistics script should now look like this:

    ARVT8.png

    The underlying ATL for the script it as follows:

    [[Jurisdiction]] has a land mass of [[StateLandArea]] square kilometers and a population in 2016 of [[StatePop2016]], [[if(percentageChange(StatePop2016,StatePop2010,1)>0)[[chooseAtRandom('up','an increase of','a rise of')]]elseif(percentageChange(StatePop2016,StatePop2010,1)<0)[[chooseAtRandom('down','a decrease of','a drop of')]]else{a change of}]] [[abs(percentageChange(StatePop2016,StatePop2010,1))]]% from 2010's figure of [[StatePop2010]]

  20. Click Preview, check the output for each row and confirm that random lexical variation has been added as intended.

Adding syntactic random variation

Okay, you have added some lexical variation: different words/phrases are chosen randomly to express the same concept. Although this is an important part of adding variation to a text, a more noticeable impact is achieved by adding syntactic variation. This involves providing alternative structures for a sentence.

Let's add some syntactic variation to your script. You'll start by building a number of different ways of expressing the content of the first sentence, then use the chooseAtRandom function to choose randomly from among them.

You could build all the required variants in a single script, but that might make things needlessly difficult to follow. To simplify the task, let's put each syntactic variant in a separate script.

Creating a new script for each syntactic variant

  1. Create a new script called StateStats1. This will contain the first variant.

  2. Copy the contents of the StateStatistics script (our current single syntactic variant) into the new StateStats1 script.

  3. Return to the StateStatistics script, select the entire content, then click Insert Script > StateStats1. This will replace the text with a single call to the StateStats1 script.

    ARVT9.png

  4. Preview the Main script to check that everything still works as intended.

  5. Create a new script called StateStats2. This will contain the second variant.

    Here you need ATL that expresses the same content as the first variant (now in StateStats1) but uses a different sentence structure. You can experiment here, or you can use the example displayed below:

    ARVT10.png

    The ATL for this example is: [[Jurisdiction]] occupies [[StateLandArea]] square kilometers. Its population has risen from [[StatePop2010]] in 2010 to [[StatePop2016]] in 2016, a rise of [[abs(percentageChange(StatePop2016,StatePop2010,1))]]%

    Note that StateStats1 and StateStats2 express the same information (both describe the jurisdiction's size and population) but differ structurally.

  6. Create a new script called StateStats3 and add a third variant. Again, you can experiment here, or you can use the example displayed below:

    ARVT11.png

    The ATL for this example is: [[Jurisdiction]] is [[StateLandArea]] square kilometers in size and has a population of [[StatePop2016]] ([[abs(percentageChange(StatePop2016,StatePop2010,1))]]% up from 2010's count of [[StatePop2010]])

    Now you have three syntactic variants. The next step is to make sure Studio will randomly choose from among them.

Inserting a call to the chooseAtRandom function

  1. Return to the StateStatistics script and add calls to the StateStats2 and StateStats3 scripts (use the Insert Script button).

  2. Insert vertical bars to separate the script calls. Once done, your StateStatistics script should look like this:

    ARVT12.png

  3. Select all content, then click Insert Function > language > chooseAtRandom. The Function Builder dialog should look like this:

    ARVT13.png

  4. Click Save to insert the function. Your StateStatistics script should now look like this:

    ARVT14.png

  5. Return the Main script and preview the narrative for each row. You should see the effect of adding random syntactic variation.

We’ve focused here on adding lexical and syntactic variation at the start of the narrative, which is often where lack of variation is most noticed. As an exercise, however, you should try adding random variation elsewhere.

Final step: Publishing a project

© Arria Data2Text Limited