Example Project: Adding Random Variation and Conditional Variation to a Narrative
Demonstrates multiple ways of adding variation to a narrative using NLG Studio. Produces individualized reports of a customer’s spending on a credit card.
Click Access Download above to get this example project for use within NLG Studio. Scroll down for the project’s documentation—including example code, sample data, and sample reports.
This documentation is organized as follows:
Introduction
This example project demonstrates ways of building variation into projects using NLG Studio. At the section level, it has random variation. It also has conditional and random variation within each section.
The output is a credit card report displaying a summary of an individual’s weekly spend, deviation in spending from the previous week, merchant credit information, and category spend statistics. Each time the narrative is previewed, the text is randomly generated in a different way — showing variation in phrasing, subject matter, document structure, and report length.
The narrative has four different sections – that may appear or be absent – showing the following:
- Amount of spend – statistics on weekly spend
- Spend deviation – week over week spend
- Merchant credit – merchant credits applied to the account
- Category of spend – a list of categories with the highest spend for the week in review
Note: This sample’s purpose is to demonstrate the various ways that linguistic variation can be added to text using NLG Studio. One example of variation shown is in the way the sample’s narrative is structured – meaning that you can randomly vary the sequence in which text appears, and you can leave certain text out when it is not relevant. So, while a credit card statement that you receive from your credit card provider would probably order the information into separate sections with headings such as Statement Balance, Additional Fees, and so on, this demonstration provides the information in a less formal, unstructured manner that changes with each preview or run.
Sample Reports
This project includes five different document plans: three produce shorter narratives and two produce longer ones. The document plans are sub-scripts to the Main script, and you can preview each one repeatedly to see their variation. If you preview the Main script, you’ll see the greatest amount of variation in the output; this is because the code in this script has conditional and random variation that impacts which of the sub-scripts (document plans) in the project are used in an individual run.
You determine whether to produce long or short narrative using "reportFormat".
To choose whether the output is a short or long narrative:
- In NLG Studio, in the Data view, in the sample data within the left section, change
"reportFormat": "long",to"reportFormat": "short", - In the left navigation bar, click Compose to go to the Compose view.
- Click Preview repeatedly to see randomly generated short narrative output instead of long narrative output.
Main
With a decrease of $198.03, your spending this week is down 40.65% from last week’s total of $487.13. You made thirty-five fewer transactions this week than last.
This week you made eleven transactions, for a total of $289.10. This equates to an average of $26.28 each.
Spending activity this period was across five categories. The largest two were hotel ($159.99, or 55.34% of your total) and restaurant ($130.25, or 45.05% of your total).
You received an aggregate of $89.88 in credits from two merchants.
You are paying 2.9% on each foreign transaction you make, which totals $19.03 this period. First Superior Bank and Trust offers several cards that have no foreign transaction fees and if you travel abroad frequently you could save a lot of money with a different card.
You have earned 713 membership rewards this period, while taking advantage of 3,243 points. Your present balance is 8,323.
On Thursday, we generated your latest statement for an amount of $1,263.84. We accepted your payment of $2,084.93 on 4/8/18. Kindly note that processing may take up to three days from receipt.
Purchase Protection can help guard suitable purchases made on your card if they are accidentally damaged, stolen, or lost. For additional information, please search “purchase protection” on our website.
Document Plan – Short 1
You have added $289.10 to your current balance of $723.72 this week. Your average purchase was $26.28 over eleven total transactions. Your spending was down 40.65% from last week’s total of $487.13. You made thirty-five fewer transactions this week than last.
Transactions this period included two credits from merchants, equaling $89.88.
Of the five areas of activity this period, the two highest spends were hotel ($159.99, or 55.34% of the total) and restaurant ($130.25, or 45.05% of the total).
Document Plan – Short 2
With a decrease of $198.03, your spending this week is down 40.65% from last week’s total of $487.13. We see thirty-five fewer transactions this week than last. You have added $289.10 to your current balance of $723.72 this week. Your average purchase was $26.28 between eleven total items.
Transaction activity this period was across five categories. The most significant two were hotel ($159.99, or 55.34% of your total) and restaurant ($130.25, or 45.05% of your total).
Transactions this period involved two credits from merchants, totaling $89.88.
Document Plan – Short 3
You increased your current balance by $289.10, giving you a new total of $723.72 this week. Your average purchase was $26.28 over eleven total transactions. Spending was $198.03 less this week vs. last, a drop of 40.65%. Transactions are down this week, thirty-five fewer than the previous week.
Activity this period was across five categories. The largest two were hotel ($159.99, or 55.34% of your total) and restaurant ($130.25, or 45.05% of your total).
You obtained an aggregate of $89.88 in credits from two merchants.
Document Plan – Long 1
On Thursday, we generated your up-to-date statement with a total of $1,263.84. We took your remittance of $2,084.93 on 4/8/18. Just remember that processing may take up to three days from delivery.
This week you engaged in eleven transactions, for a total of $289.10. This equates to an average of $26.28 per transaction.
With a decrease of $198.03, your spending this week is down 40.65% from last week’s total of $487.13. Transactions are down this week, thirty-five fewer than the previous week.
Activity this period was across five categories. The most significant two were hotel ($159.99, or 55.34% of your total) and restaurant ($130.25, or 45.05% of your total).
You paid $19.03 in foreign transaction fees this period. Foreign transaction fees are calculated at a rate of 2.9%, and you could save money by upgrading to the Universal Traveler Gold card, which has no fees on foreign transactions.
You grossed a sum of $89.88 in credits from two vendors.
You have earned 713 membership rewards this period and used 3,243 points. Your current balance is 8,323.
Document Plan – Long 2
Your spending was down 40.65% from last week’s total of $487.13. Compared to last week, purchases are down this week by thirty-five.
This week you made eleven transactions, for a total of $289.10. This equates to an average of $26.28 each.
Activity this period was across five categories. The highest two were hotel ($159.99, or 55.34% of your total) and restaurant ($130.25, or 45.05% of your total).
Transactions this period included two credits from merchants, equaling $89.88.
You paid $19.03 in foreign transaction fees this period. Foreign transaction fees are calculated at a rate of 2.9%, and you could save money by upgrading to the Universal Traveler Gold card, which has no fees on foreign transactions.
You earned 713 membership rewards this period and enjoyed 3,243 points. Your present balance is 8,323.
Your up-to-date statement was generated this past Thursday for a total of $1,263.84. We received your remittance of $2,084.93 on 4/8/18. Kindly note that processing can take up to three days from delivery.
Example Data
The example that follows shows the data structure. (This is an excerpt; it does not represent the full sample report.)
{
"reportPeriod": "week",
"reportFormat": "long",
"cardProduct": "Silver Rewards",
"foreignTransactionFeeRate": "2.9%",
"statementSummary": {
"StatementAmount": "1263.84",
"StatementDate": "5/5/18",
"StatementDayOfWeek": "Thursday",
"StatementPostedWithinWeek": "true",
"LastPaymentReceived": "2084.93",
"LastPaymentReceivedDate": "4/5/18",
"PaymentReceivedWithinWeek": "true",
"LastPaymentReceivedDayOfWeek": "Thursday",
"LastPaymentProcessed": "2084.93",
"LastPaymentProcessedDate": "4/8/18",
"CurrentBalance": "723.72",
"AirlineFeeCreditBalance": "85.87",
"MembershipRewardBalance": 8323
},
"categorySpend": [
{
"category": "restaurant",
"spend": "130.25"
},
{
"category": "merchandise",
"spend": "-36.51"
},
{
"category": "groceries",
"spend": "46.77"
},
{
"category": "communications",
"spend": "39.99"
},
{
"category": "hotel",
"spend": "159.99"
}
],
"transactionDetail": [
{
"TransactionAmount": "31.17",
"TransactionDay": "Sunday",
"TransactionDate": "4/15/18",
"TransactionTimeEDT": "19:35:18",
"MerchantName": "the bowery road",
"MerchantCategoryName": "restaurant",
"MembershipRewardsEarned_pending": "61",
"MembershipRewardsBurned": "0",
"RewardDollarsEarned_pending": "0",
"MerchantCreditReceived": "no",
"ForeignTransactionFeeAmount": "3.02"
},
{
"TransactionAmount": "8.03",
"TransactionDay": "Monday",
"TransactionDate": "4/16/18",
"TransactionTimeEDT": "8:16:39",
"MerchantName": "juans",
"MerchantCategoryName": "restaurant",
"MembershipRewardsEarned_pending": "12",
"MembershipRewardsBurned": "0",
"RewardDollarsEarned_pending": "0",
"MerchantCreditReceived": "no",
"ForeignTransactionFeeAmount": "0"
},
{
"TransactionAmount": "45.63",
"TransactionDay": "Saturday",
"TransactionDate": "4/21/18",
"TransactionTimeEDT": "11:17:32",
"MerchantName": "sukkhi thai",
"MerchantCategoryName": "restaurant",
"MembershipRewardsEarned_pending": "91",
"MembershipRewardsBurned": "0",
"RewardDollarsEarned_pending": "0",
"MerchantCreditReceived": "no",
"ForeignTransactionFeeAmount": "0"
},
{
"TransactionAmount": "159.99",
"TransactionDay": "Saturday",
"TransactionDate": "4/21/18",
"TransactionTimeEDT": "22:31:27",
"MerchantName": "supreme hotel chain",
"MerchantCategoryName": "hotel",
"MembershipRewardsEarned_pending": "320",
"MembershipRewardsBurned": "0",
"RewardDollarsEarned_pending": "0",
"MerchantCreditReceived": "no",
"ForeignTransactionFeeAmount": "15.99"
}
],
"previousWeek": {
"totalTransactionAmount": "487.13",
"totalTransactions": "46",
"topCategory": "restaurant"
}
}