Branch Logic Syntax Guide
Branch Rules Must Evaluate to True or False
When you create a Branch, you configure Wordsmith to write a certain word, phrase, or sentence if a conditional rule is true.
Those rules are written in the top box of the Branch window, which is labeled “If this is true.” Wordsmith will determine if that rule is true or false for that particular row of data. If a rule is true, then the associated text in the “Then write” box will show in the narrative.
You can use different functions in Branches based on the type of data you're using: Numbers, Text, Lists, Dates, and True/False.
Creating Branch Rules
Rules in Wordsmith can include comparisons and logical expressions.
| Usable Across All Data | |
|---|---|
| = | Equal to |
| != | Not equal to |
| and | To evaluate more than one condition that must both be True |
| or | To evaluate more than one condition where either can be True |
Logical expressions include the words “and” and “or”. They allow you to link multiple comparisons together.
For example, you might want to write a certain phrase only if sales and profits are both up.
This sentence will be written if sales are up and profits are up.
You can use more than one logical expression in a condition. Use parentheses to keep Wordsmith organized, just like the order of operations. For example:
This sentence will be written if sales are up and either profits are up or costs are down.
The rule means something different if you change parentheses:
This sentence will be written if sales and profits are both up or if costs are down.
Using Math
For data categorized as a Number
| For Numbers | |
|---|---|
| = | Equal to |
| != | Not equal to |
| > | Greater than |
| < | Less than |
| >= | Greater than or equal to |
| <= | Less than or equal to |
| + | Add |
| - | Subtract |
| * | Multiply |
| / | Divide |
| % | Modulo |
| percentChange | Calculate the percentage difference between two values. |
| min | The minimum value for a data variable across all rows in the data uploaded to that Project. |
| max | The maximum value for a data variable across all rows in the data uploaded to that Project. |
| average | The average value for a data variable across all rows in the data uploaded to that Project. |
| sum | The sum of all values for a data variable across all rows in the data uploaded to that Project. |
These comparisons can be used to compare one data point to another:
Or, to compare a data point to a number
Within Branch rules, you can do math using the standard +, -, *, / and % signs. For example:
You’ll only be able to do mathematical comparisons on data that represent real numbers. Wordsmith can’t compare text variables. A string of text like “cheese” is not greater than, equal to, or less than “socks” — at least as far as Wordsmith knows. As long as data represent real numbers, you can do math on them in your Branch rules.
Adding modulo, %, to a condition will find the remainder of division. You can use it as a variability tool to say something in particular rows of your data. For example, by using the unique ID automatically assigned to each row of your data, the condition below would return TRUE in every fifth row of your data. So every fifth piece of content could have a particular word, phrase, or sentence.
This sentence would be written if the SKU for the product is an even number.
Use percentChange to calculate the percentage difference between two data variables. The order of the data variables in the function is important - the first data variable should be the original value, and the second data variable should be the value that has changed. The calculation works like this:
percentChange (original_value, changed_value) = ((original_value - changed_value) / original_value) * 100
In this example, we want to know the percent change between the original value (revenue_previous) and the changed value (revenue_current). If it's greater than 25%, this phrase will be written.
The min, max, average, and sum functions all work the same way. They'll use all of the values for a particular data variable based on the data uploaded to that Project. If you're using the Wordsmith API, the data you send through the API will be compiled with the data uploaded to the Project. Every time you edit your data on the Data tab, the data will be reset and whatever you sent via the API will not be included in these calculations.
These are the only functions that compare data across rows.
Using Text Attributes
| For Text | |
|---|---|
| = | Equal to |
| != | Not equal to |
| "" | Null value in your data file |
| includes | Will return True if specific text is in a row of your data file, even a partial match |
| excludes | Will return True if specific text is not in a row of your data file, even a partial match |
You can also use text columns in your Branch rules, but they work slightly differently. You’re simply creating a rule that applies if a certain string of text appears in a column. Use the = operator and double quotes around the value for a scenario where you want an exact match.
This sentence will be written if the person's title is "Chief Executive Officer".
Or you can search for a partial match of a text string.
This sentence will be written if the the person's title has chief in it, which could be Chief Executive Officer, Chief Technology Officer, Chief Revenue Officer, etc.
Don't forget to use quotes around Text when using it in a Branch rule.
Using Date Functions
| For Dates | |
|---|---|
| = | Will check for an exact date. Enter the date in quotes and use slashes, i.e. "4/1/16". |
| != | Will check that your data does not match an exact date. Enter the date in quotes and use slashes, i.e. "4/1/16". |
| > | True for dates that come after the date in your data. |
| >= | True for dates that come after to or on the same day as the date in your data. |
| < | True for dates that come before the date in your data. |
| <= | True for dates that come before or on the date in your data. |
| getWeekday | Will return a numerical value for the day of the week. With Sunday = 1 and Saturday = 7. |
| getDay | Will return the day part of a date as a number. |
| getMonth | Will return the month part of a date as a number. |
| getYear | Will return the year part of a date as a number. |
| daysBetween | Will calculate the number of days between 2 dates. |
| monthsBetween | Will return the months between 2 dates as a whole number. |
| yearsBetween | Will return the years between 2 dates as a whole number. |
| daysAhead | Allows you to add days to a date and return that new date. |
| daysAgo | Allows you to subtract days from a date and return that new date. |
| monthsAhead | Allows you to add months to a date and return that new date. |
| monthsAgo | Allows you to subtract months from a date and return that new date. |
| yearsAhead | Allows you to add years to a date and return that new date. |
| yearsAgo | Allows you to subtract years from a date and return that new date. |
Get functions will parse out different parts of the date from your data. So for example, if the date = 4/1/16, then
getWeekday(date) = 7
getDay(date) = 1
getMonth(date) = 4
getYear(date) = 2016
You can use getWeekday to reference the days of the week.
This phrase will be written if the date is Monday, Tuesday, or Wednesday.
You can use getMonth to denote seasons.
"Spring" will be written if the date is in March, April, or May.
And you can compare the years of two different dates using getYear.
This Branch customizes the sentence based on a report's date and the previous report's date being the same year or not.
Between functions will allow you to compare time between two dates: the date from your data and a new date you specify in the function. Say the date in the data is 4/1/16, then
daysBetween(date,"5/31/16") = 30
monthsBetween(date,"5/31/16") = 1
yearsBetween(date,"5/31/16") = 0
You can also get the time between two data variables that are dates.
This Branch will customize the sentence based on the difference between two dates being less than 30 days or less than 12 months.
Ahead and Ago functions let you perform math on dates, like adding or subtracting time, and then return that new date. Ahead functions will add time to a date, and Ago functions will subtract time. Use numbers to add and subtract time in days, months, or years. So if the date in the data is 4/1/16, then
daysAhead(date, 2) = 4/3/16
daysAgo(date, 2) = 3/30/16
monthsAhead(date, 2) = 6/1/16
monthsAgo(date, 2) = 2/1/16
yearsAhead(date, 2) = 4/1/18
yearsAgo(date, 2) = 4/1/14
You can even combine the date functions in interesting ways.
These rules are subtracting 6 months from the date, then getting the year for that new date. You can then customize the sentence to say the last report came out last year or this year.
Using Time
| For Time | |
|---|---|
| = | Will be true if two times are the same. Make sure to put the value in quotes or insert another Time data variable. |
| != | Will be true if two times are not the same. |
| > | Will be true if the time is later than the subsequent data. |
| >= | Will be true if the time is the same or later than the subsequent data. |
| < | Will be true if the time is earlier than the subsequent data. |
| <= | Will be true if the time is the same or earlier than the subsequent data. |
You can compare Time data variables to each other or to a new value. When comparing to a new value, make sure to put the value in quotes. The new value can be in any Time format recognized by Wordsmith (even if it is not the same format as the original data).
In this example, you can customize the text displayed based on the data for arrival_time. If arrival time is earlier than noon, "morning" will be written, if it is between noon and 5pm, "afternoon" will be written, and if it is later than 5pm, "evening" will be written.
You can also compare two Time data variables to each other.
This Branch allows you to see if one Time data variable comes before or after another Time data variable.
Using Lists of Objects
A list is a series of words separated by commas in just one cell of your data file. For example, in the data below, the data in the "top neighborhoods" column is a List.
You can use all the same syntax for Lists that you can with Text, plus the includes, excludes, and count functions.
| For Lists | |
|---|---|
| = | Equal to |
| != | Not equal to |
| "" | Blank value in your data |
| includes | Will return True if the exact text string is included in a list on that row of your data |
| excludes | Will return True if the exact text string is not included in a list on that row of your data |
| count | Count the number of objects in a list |
| sort | Sort the objects in a list in ascending or descending order |
| valueAt | Pull out one object in a list |
Lists work similarly to Text. To search for an exact match, use quotes around the text string exactly as it appears in your data file.
This rule will be True for data that has these exact 3 objects: "el cerrito, south park, la mesa".
Using the exact match function for Lists is fairly uncommon. You'll likely want to search for one object in the list. And to do that, you can use the includes and excludes functions.
This rule will return True for data that has "El Cerrito" as a top neighborhood.
To count how many objects are in a list, use the "count" function. You can use "count" to treat lists with just one object differently than lists with more than one object. Now we can say The top neighborhood is... if there is only one object in that list. Or The top neighborhoods are... if there is more than one object.
This Branch allows us to write a different sentence if there is just one top neighborhood in the area verses multiple neighborhoods.
You can re-order the objects in a List by using the sort function, either ascending or descending. To sort the List in ascending order, the syntax is sort(data_variable, "asc") and to put the List in descending order, sort(data_variable, "desc").
In this example, we have a List of states (top_states). Using the sort function, we can put that list in alphabetical order.
To pull out a specific object in a List use the valueAt function. The objects start at 0, so valueAt(data_variable, 0) would give you the first object in the List, valueAt(data_variable, 1) would give you the second, and so on. You can even combine the sort and valueAt functions to first sort the objects in a List and then pull out a specific one.
In this Branch, we're checking to see if the first object is the same for two Lists, the top_states_volume and top_states_revenue.
For more information on Lists, check out the Data Types page.
Using True/False Data
True/False data is data that only includes TRUE or FALSE values. In addition to "true" and "false", Wordsmith recognizes "yes" and "no", and their abbreviations.
All of these are TRUE:
- true
- t
- yes
- y
All of these are FALSE:
- false
- f
- no
- n
The data variable "wifi capable" is True/False data. If the TV has wifi capability, the data here will be "true". To write a Branch rule for that, we can write wifi_capable = true.
Accounting for Empty Cells
Even if your data set has some empty cells (or if you think it might but aren’t sure), you can still add a Branch Condition using two quotation marks side by side with nothing in the middle: “”.
This condition will return True if the data is blank for "expected precipitation".
expected_precipitation = “”
This condition will return True if there is data for "expected precipitation".
expected_precipitation != “”
In this example, the sentence will only be written if there is a value for the data variable "expected precipitation". If that data is blank, then nothing will be written.
Changing from Singular to Plural
If you need to change parts of your narrative to a singular or plural version based on something in your data, you can do that with a Branch. You'll just need to have a data variable that determines if that word or words needs to be singular or plural. Here's an example.
Updated over 4 years ago