Skip to main content

Using language functions

You add language functions to your text to make it grammatically correct and human-sounding. We are going to add some text describing who manages the office.

  1. In the DescribeOffice script, add the following sentence: The office is managed by a X named Y Z.

    • The X is a placeholder for a job role. Add this ATL to replace X: [[office.manager.role]]

    • The Y is a placeholder for a person’s first name. Add this ATL to replace Y: [[office.manager.firstName]]

    • The Z is a placeholder for a person’s last name. Add this ATL to replace Z: [[office.manager.surname]]

    The ATL in the script should look like this (the new ATL is underlined in red):

    LF JSON 01 (new).png

  2. Go to the Main script and preview the text.

    LF JSON 02 (new).png

    Notice that the system intelligently chooses a or an based on the word following the article. NLG Studio makes this correction automatically.

    For more complex language operations, NLG Studio provides a number of different language functions. Let’s try continuing our text.

  3. In the DescribeOffice script, add the following sentence: He has X employees working for him.

    The X is a placeholder for the number of employees working for the office head.

  4. Replace the X with the following ATL: [[office.employees]]

  5. Go to the Main script and click Preview.

    LF JSON 03 (new).png

    Okay. The narrative is looking better, but it still needs work. How many language problems can you spot?

    For one: not all office heads are male. We need to fix some pronouns. Two of NLG Studio’s language functions will fix this for us: gender and pronoun. The pronoun function requires gender, so these two functions are almost always used together. The gender function takes a first name and returns the most common gender for that name.

  6. In the DescribeOffice script, replace He, with the following ATL: [[gender(office.manager.firstName)]]

    LF JSON 04 (new).png

  7. Go to the Main script and click Preview.

    You should see the system return Male for Frank, Female for Maria, and so on. That’s not what we need!

    LF JSON 05 (new).png

    This is why we also need the pronoun function. We need to convert the instances of Male and Female to He and She, respectively.

  8. Return to the DescribeOffice script, click and drag to select the ATL snippet [[gender(office.manager.firstName)]], and then click Insert Function > language > pronoun to open the Function Builder dialog.

    Note

    The pronoun function has a lot of options. You only need to fill in the parameters that matter to you.

  9. Click Save to apply the function. (Because you selected the ATL snippet before opening the function builder, the necessary parameters were already populated, so you don’t actually need to do anything else before clicking Save.)

    The amended ATL should look like this: [[pronoun(gender(office.manager.firstName))]]

    For the pronoun at the start of our sentence, we only needed to enter [[gender(office.manager.firstName)]] in the GENDER parameter. This makes the system correctly generate He has X… or She has X…. But the end of the sentence also includes a pronoun. In this case, however, the pronoun is used as an object. So we need the output to read him or her. This is where the function's other parameters come in.

    We’ll follow the same steps as before, but this time we’ll set the pronoun’s type to object.

  10. Still in the DescribeOffice script, replace the word him with this ATL: [[gender(office.manager.firstName)]].

  11. Click and drag to select the ATL snippet [[gender(office.manager.firstName)]] and then click Insert Function > language > pronoun.

  12. In the Function Builder, click in the TYPE field and select object from the drop-down.

    LF JSON 06 (new).png.png

  13. Click Save.

    The ATL snippet should now look like this: [[pronoun(gender(office.manager.firstName),'','object','')]]

    LF JSON 07 (new).png.png

  14. Go to the Main script and click Preview.

    LF JSON 08 (new).png

    You can see that our system is now able to address people’s gender appropriately.

    However, there is still a major linguistic error. For Houston, the report says She has 1 employees working for her. This noun phrase (1 employees) is what we call a countable expression, meaning that it can appear in the singular or the plural.

  15. Return to the DescribeOffice script, select the noun phrase [[office.employees]] employees, and then click Insert Function > language > countable.

    Note: Here, we are selecting not just the ATL snippet but also the word employees following the ATL snippet.

  16. In the Function Builder, the first parameter is auto-populated with the whole noun phrase. Rearrange this, cutting and pasting the head noun employees to put it as the parameter in the NOUN field:

    LF JSON 09 (new).png.png

    Note

    It doesn’t matter whether you put a singular or plural noun in the NOUN field. Studio will try to make sense of whatever you provide. In this instance, if you entered employee instead of employees, the result would be the same.

    The countable function doesn’t just make sure the noun is in the right form; it also lets you format the number. Countable expressions typically look better if the number is spelled out (at least when the expression is a small number). The NUMBER FORMAT parameter for this function lets you turn this off, but we’re going to use it.

  17. Click Save.

    When you return to the script editor, the ATL [[countable(office.employees,'','employees')]] should have replaced [[office.employees]] employees.

  18. Go to the Main script and click Preview.

    You should see sentences such as:

    He has three employees working for him.

    She has one employee working for her.

    LF JSON 10 (new).png

In this step of the tutorial, we learned:

  • Studio automatically corrects "a" to "an" depending on the word following the article; you don’t need to add a function for this.

  • Use of the pronoun function, both on a word that was a subject and a word that was an object.

  • Use of the gender function.

  • Use of the countable function.

There are many different language functions, and Arria NLG is always adding more. Explore and see what Studio can do for you.

Next, we’ll add some more variation to our narrative.

Adding conditional variation to your JSON project

© Arria Data2Text Limited