Why should I try out these samples?


Would you rather read about what a factory makes, or take a live tour and see what the factory makes as it is being made? If you just read the documentation here, you’re missing out.


What can I do with the sample projects available here?

The reason to open our samples in Studio is so that you can learn about how to use the tool while watching its functionality in action. You can get information by reading the text and code in the sample’s scripts, but more importantly, you can then immediately see how the code works when you preview it.

For example, this code:

The function called countable builds countable phrases like [[countable(1,'','cat')]] or [[countable(2,'','dog')]]. This method automatically pluralizes when it needs to, and it attempts to choose the correct plural form. For example: [[countable(3,'','fox')]], [[countable(4,'','child')]], or [[countable(5,'','appendix')]]. The second argument lets you include modifiers like so: [[countable(6, 'great', 'example')]].

… when previewed, shows the output that follows. (The bolded text shows the output calculated from the code.)

The function called countable builds countable phrases like one cat or two dogs. This method automatically pluralizes when it needs to, and it attempts to choose the correct plural form. For example: three foxes, four children, or five appendices. The second argument lets you include modifiers like so: six great examples.

Preview the narrative

We’ve already mentioned the most basic thing you can do with an Arria sample project: previewing the narrative that is generated from the sample’s scripts. This is where Studio doesn’t just tell you what it can do, it shows you.

After you open a sample in Studio, just click the Preview button at the top right of the screen. Preview works like this:

When you compare the narrative’s preview with the content of the project’s scripts, you see how NLG Studio takes in data, applies code, and outputs narrative.

Look at the code

Say you want to learn about how you can add linguistic variation to narratives. In that case, you definitely want to check out the sample built specifically to demonstrate that capability. Take a look at the way that the chooseAtRandom function works, and how conditionals are built.

Check out the variables used in the sample

Variables store the values that are used throughout the project’s narrative. They are computed once from the data each time a narrative is generated. They can be simple values, or they can be complex snippets of code. By looking at a sample’s variables, you can get a better understanding of how the project works.

After you’ve looked at the project’s variables in the Variables view, look at the project’s scripts to spot the variables “on location”, then preview the scripts to see the variables in action.

Make changes to the sample data

You can make changes to the sample data from right inside the Data view in Studio. Then preview again, to see how your revisions change the narrative.

As you’re doing this, think about which changes you would need to make to accommodate the structure of your own data, if you were going to deploy a customized version of the sample project for your own use.

Find solutions to coding challenges

For Studio users who are ready to level-up on their NLG skills, another important use for the samples is as a reference that can point to solutions to problems you could be having in your own project. You’re likely to find ways of accomplishing things you’re trying to do in your own project inside the code of a sample project. For example, you may wonder how to group a list of objects by the sum of one of their attributes, and you could find an example of how to do that sitting in one of the samples. Why struggle to solve a problem that someone else has already solved?

Revise the sample’s scripts to fit your own needs

If you have a use case in mind for generating narratives, then ideally you will download a sample project that has a purpose similar to your use case. Find the sample best suited to your needs, then revise the text and the code to make it your own.

Upload your own data to replace the sample data

When you’re ready to try out how the project will work when deployed with real data, upload a new set of your own sample data that accurately represents the structure of the real data you expect your project to work on when it is deployed.