Skip to main content

Using language functions

Let’s start with the phrase his first term in the first sentence of the HeadOfState script.

This needs two fixes: (1) the pronoun should reflect the gender of the person we are talking about; and (2) the word first should be replaced by a variable that outputs the correct number of terms.

To generate the correct pronoun

  1. Select his in the first sentence, then click Insert Function > language > pronoun. This will open the Function Builder dialog.

  2. Delete his from the GENDER OR NAME field, then select HeadOfGovt from the drop-down.

  3. Click in the TYPE field and select possessive from the drop-down. This is necessary because in this case we need to use the possessive form of the pronoun (e.g. "her" rather than "she").

  4. Leave the other fields blank. The Function Builder dialog should look like this:

    LF1.png

  5. Use the local preview to check that Studio is producing the correct pronoun for each row.

  6. Click Save.

To fix the reference to the count of terms

  1. Select first in the first sentence, then click Insert Function > language > numToWords. This will open the Function Builder dialog.

  2. Delete first from the NUMBER field, then select Terms from the drop-down. This variable outputs a number, which the function will convert into a word.

  3. Click in the TYPE field and select ordinal from the drop-down. This is necessary because in this case we want the number to be ordinal rather than cardinal (e.g. first rather than one)

  4. Leave the other fields blank. The Function Builder dialog should look like this:

    LF2.png

  5. Use the local preview to check that Studio is producing the correct text for each row.

  6. Click Save. Your HeadOfState script should now look like this:

    LF3.png

  7. Click Preview. The output text for Row 1 should be:

    The Premier, Gladys Berejiklian (Liberal), is in her first term. He has one daughter, Grace, and two sons, Joseph and Noah.

To generate the correct pronoun (second sentence)

Now, let's look at the second sentence. First, you need to ensure the pronoun reflects the gender of the person we are talking about.

  1. Select He in the second sentence, then click Insert Function > language > pronoun. This will open the Function Builder dialog.

  2. Delete He from the GENDER OR NAME field, then select HeadOfGovt from the drop-down.

  3. Leave the other fields blank. You don't need to specify the TYPE parameter this time because the parameter default (subject) is correct in this case.

  4. Click Save. Your HeadOfState script should now look like this:

    LF4.png

  5. Click Preview. The output text for Row 1 should be:

    The Premier, Gladys Berejiklian (Liberal), is in her first term. She has one daughter, Grace, and two sons, Joseph and Noah.

Adding a complex conditional

Fixing the rest of the second sentence is more complicated because you must consider, and then find a way to deal with, a number of different possibilities (also known as cases). These are:

  1. The Head of State has no children.

  2. The Head of State has only daughters.

  3. The Head of State has only sons.

  4. The Head of State has both sons and daughters.

You need to build a conditional expression that covers all four cases. Complex conditionals are easiest to build from the bottom up: you construct each case individually, then combine them into an appropriate conditional. We'll start with the easiest case.

Case 1: Head of State has no children

  1. Copy the second sentence.

  2. Insert a paragraph break, then paste your copied sentence.

  3. Delete has one daughter, Grace, and two sons, Joseph and Noah from the pasted sentence, then type does not have any children in its place. Your script should now look like this:

    LF5.png

Case 2: Head of State has only daughters

  1. Copy the Case 1 sentence, insert a paragraph break, then paste your copied sentence.

  2. Delete does not have any children from the pasted sentence, then type has X daughters in its place.

  3. Select X, then click Insert Variable and select NumDaughters from the drop-down.

    LF6.png

    The next step is to recognize that the noun phrase corresponding to NumDaughters daughters is what we call a countable expression, meaning it can appear in singular form (e.g. one daughter) or plural form (e.g. two daughters). You can cover both possibilities by using the countable function.

  4. Select the noun phrase NumDaughters daughters, then click Insert Function > language > countable. This opens the Function Builder dialog.

  5. Click in the COUNT field, then delete daughters.

  6. Click in the NOUN field and type daughters (do not select the Daughters variable).

    The Function Builder dialog should look like this:

    LF7.png

    Note

    It usually doesn’t matter whether you specify a singular or plural noun in the NOUN field; Studio will try to make sense of whatever you provide.

  7. Click Save. Your script should now look like this:

    LF8.png

Case 3: Head of State has only sons

  • Construct a Case 3 sentence that reports only the number of sons. Just repeat the steps for Case 2 (see above), inserting different text and variables as required. When finished, your script should look like this:

    LF9.png

    The underlying ATL for your Case 3 sentence (click the ATL View button) should look like this:

    [[pronoun(HeadOfGovt)]] has [[countable(NumSons,'','sons')]]

Case 4: Head of State has both sons and daughters

  1. Copy your Case 1 sentence, insert a paragraph break, then paste your copied sentence.

  2. Delete does not have any children from the pasted sentence, then type has N daughters and M sons in its place.

  3. Replace N daughters and M sons with calls to the countable function. You have already built the required function calls in your Case 2 and Case 3 sentences, so just copy and paste the appropriate elements. When finished, your script should look like this:

    LF10.png

To list the names of the children

You're not finished yet. Next you need to list the names of the children. This information is in the Daughters and Sons columns of the data table, so you should be able to retrieve them by inserting the relevant variables. Let's try this with the sentence that talks only about the number of daughters (Case 2).

  1. Position your cursor at the end of the Case 2 sentence (but before the full stop) and insert a comma and a space.

  2. Click Insert Variable and select Daughters from the drop-down.

  3. Select the Case 2 sentence, then click Preview. You should see this for Row 1:

    LF11.png

    Don't worry about this error. It will be fixed when you build the conditional.

  4. Click Next to preview Row 2. The text output should be:

    He has two daughters, Cate, Laura.

    The output text is fine when there is just one daughter; but when there is more than one, the list of names is not punctuated properly. It would be better to see two names here separated by "and". We achieve this using the list function.

    Important

    For the list function to do its work, Studio needs to know that your data contains a list — because rather than a list, it could just be a string that happens to contain one or more commas.

  5. Click Variables to access the Variables view.

  6. Click on Daughters in the variables list.

  7. Click in the VARIABLE TYPE field and select LIST from the drop-down.

  8. Click Done.

  9. Repeat steps 7 and 8 for the Sons variable. Your variables list should now look like this:

    LF12.png

  10. Click Compose.

  11. Select the Daughters variable in the Case 2 sentence, then click Insert Function > language > list. This will open the Function Builder dialog.

  12. Delete [[Daughters]] from the CONJUNCTION field.

  13. Click in the first W field and select Daughters from the drop-down. The other fields can be left blank.

    LF13.png

  14. Click Save. Your script should look like this:

    LF14.png

  15. Repeat steps 11 to 14 to add the required lists for the Case 3 and Case 4 sentences. When finished, your script should look like this:

    LF15.png

    You need to do one more thing before we put together the conditional statement that will use these four sentences. In the case where there are both sons and daughters, we want to precede the individual counts with a count of the total number of children. For example: He has two children: one daughter, Mary, and one son, Fred.

  16. Place your cursor after has in your Case 4 sentence, insert a space, then click Insert Function > math > sum.

  17. Select NumDaughters in the X field, then select NumSons in the Y field, then click Insert.

    This function call computes the total number of children. Next, we need to combine this with the appropriate noun to build a countable expression that presents the information correctly.

  18. Highlight the new function call, then click Insert Function > language > countable.

  19. Type child in the NOUN field, then click Save.

    LF16.png

  20. Place a colon after the new function call. Your script should now look like this:

    LF17.png

    The underlying ATL for the Case 4 sentence should be:

    [[pronoun(HeadOfGovt)]] has [[countable(sum(NumDaughters,NumSons),'','child')]]: [[countable(NumDaughters,'','daughters')]], [[list('','','',Daughters)]], and [[countable(NumSons,'','sons')]], [[list('','','',Sons)]].

    Now you have all the elements to build the conditional.

To build the conditional

  1. Insert a vertical bar ('|') after each of the first three case sentences.

    LF18.png

    Each case sentence, having been separated this way, will be used as a RESULT in the conditional expression. If the last fragment is not terminated with a vertical bar, it will be used as the DEFAULT RESULT.

    Tip

    Do not put a vertical bar after the Case 4 sentence; we want it to be used as the default.

  2. Select all four case sentences, including the vertical bar separators.

  3. Click the Insert Conditional button. This opens the Conditional Builder dialog. The result fields should be populated already.

  4. For Case 1, click in the PARAMETER A field and type NumDaughters+NumSons. Then set the condition to Is Equal To and enter 0 for PARAMETER B. This deals with the "no children" case.

  5. For Case 2, click in the PARAMETER A field and select NumSons. Then set the condition to Is Equal To and enter 0 for PARAMETER B. This deals with the "only daughters" case.

  6. For Case 3, click in the PARAMETER A field and select NumDaughters. Then set the condition to Is Equal To and enter 0 for PARAMETER B. This deals with the 'only sons' case.

  7. No fields should be populated for Case 4 in the Function Builder dialog. Check that the ATL for our Case 4 sentence ("sons and daughters") is the DEFAULT RESULT field.

    LF19.png

    Note

    It's worth pausing here to observe a few things about conditionals, and about the logical structure of our conditional.

    Conditionals work by returning the first result for which the condition is met. Therefore, Studio only checks the condition for Case 2 if the data being analyzed fails to satisfy the condition for Case 1.

    If Studio progresses to Case 2, the Head of State must have at least one child. Therefore, to determine if the Head of State has only daughters, you just need to check if the number of sons is zero. Similarly, to determine if the Head of State has only sons (Case 3), you just need to check if the number of daughters is zero.

    If none of the above conditions are satisfied, then the Head of State must have both daughters and sons, which is our default result.

  8. Click Build to insert the conditional into your script. Your script should now look like this:

    LF20.png

    The underlying ATL for the conditional should be:

    [[if(NumDaughters + NumSons==0){[[pronoun(HeadOfGovt)]] does not have any children.}elseif(NumSons==0){[[pronoun(HeadOfGovt)]] has [[countable(NumDaughters,'','daughters')]], [[list('','','',Daughters)]].}elseif(NumDaughters==0){[[pronoun(HeadOfGovt)]] has [[countable(NumSons,'','sons')]], [[list('','','',Sons)]].}else{[[pronoun(HeadOfGovt)]] has [[countable(sum(NumDaughters,NumSons),'','child')]]: [[countable(NumDaughters,'','daughters')]], [[list('','','',Daughters)]], and [[countable(NumSons,'','sons')]], [[list('','','',Sons)]].}]]

  9. Delete the second sentence in the first paragraph, then remove the paragraph break between the first and second paragraph.

    LF21.png

  10. Click Preview. The output text for Row 1 should be:

    The Premier, Gladys Berejiklian (Liberal), is in her first term. She does not have any children.

  11. Click Next. The output for Row 2 should be:

    The Premier, Daniel Andrews (ALP), is in his first term. He has three children: two daughters, Cate and Laura, and one son, Luke.

  12. Click Main to return to the Main script and click Preview.

  13. Check that the results are as expected. The output for Row 1 should be:

    New South Wales has a land mass of 800,641 square kilometers and a population in 2016 of 7,618,200, up 5.2% from 2010's figure of 7,238,800. The capital city, Sydney, has a population of 4,526,479, which is up 8.2% from 2010's count of 4,183,471. Today the capital is home to 59.4% of the state's population.

    The Premier, Gladys Berejiklian (Liberal), is in her first term. She does not have any children.

    If so, you have successfully built your first Studio application!

Next you'll learn how to improve the application further by adding random variation.

Adding random variation

© Arria Data2Text Limited