Guest Post : Time Based Reasoning Worked Example
It’s with great pleasure that I introduce you to Evert Fernandes, CTO at Magia Consulting UK Ltd. A self-confessed OPA geek, Evert has stepped up and written this article about Time Based Reasoning (and hopefully some more ) for the OPA Hub Website. Thank you Evert and…over to you!
Time Based Reasoning (TBR) – also known as Temporal Reasoning – is one of those subjects that new OPA developers tend to struggle with. It’s a more advanced subject that – once mastered – can provide huge benefits to your project.
In this article I will try to explain what TBR is, present a use case and provide a walk-through on turning the use case into rules.
So, what exactly is Time Based Reasoning?
Time Based Reasoning allows the rule developer to create rules that include attributes which contain values that are subject to change over time.
It is able to conclude rules like:
- What’s the amount of daily benefit the citizen was entitled to on June 26th, 2017?
Time Based Reasoning Worked Example
Let’s have a look at the following use case:
“How much benefit is the citizen entitled to between 01-01-2017 and 31-12-2017 (inclusive)”
The following rules apply:
- If the person is not married, the daily allowance is $10. If the person is married the allowance is $14
- The person can only claim benefit if the daily income is less than $200.
For the sake of simplicity, we will only look at a binary relationship status, married and single. The real world is more nuanced and complicated, but feel free to expand on this example. 😉
As you can see, the mix of variables already creates quite a complex and fluid situation, especially considering that any of the variables are subject to change over the period in question (01/01/2017 – 31-12-2017).
So, let’s start by looking at the first element and create some rules:
There are a number of things happening in these rules, let’s take a closer look.
First of all, a rule table has been created (ALT + Z) to determine the daily allowance amount based on marriage status, $14 when married and $10 when single. The single status is implied by the ‘otherwise’ conclusion, i.e. the person is single because the person is not married.
The second rule calculates the total allowance over the time period, starting on January 1st 2017 and ending on January 1st 2018. The reason the end date is January 1st 2018 and not December 31st 2017 is because the end date is not included, so we simply add a day.
The function is called IntervalDailySum and takes in three parameters:
- The start date (inclusive) of the period over which the calculation needs to take place;
- the end date (exclusive) of the period over which the calculation needs to take place;
- the rule text of the attribute over which the total daily allowance over the period needs to be calculated.
In this example, we provide hard coded values for the start and end dates. In the real world, the start and end dates will most likely come from date attributes.
We now need to test the rules. In order to do this, we start the OPM debugger and head to the data tab:
As you can see, not a lot is happening here. Let’s give the citizen a marital status by setting the value of ‘The citizen is married’ to ‘True’.
So far, so good. We have a marital status and OPA is able to work out the total allowance (365 days x $14 = $5110).
Let’s now assume that the person was single at the start of 2017, got married on March 1st 2017 and was single again on September 1st 2017 (don’t worry, they’re still friends! 😉).
How do we enter that data? OPA provides a handy feature called ‘Change Points’ to handle this.
Let’s reset the value for the citizen marital status:
Click on ‘Change Points’:
What this allows us to do is to take the attribute and set different values for different slices of time.
You can use ‘Add’ to add a new change point. Once a new point is created, you can set the date and value at that point in time.
Let’s add two change points. One on March 1st 2017 with a value of True and the other on September 1st 2017 with a value of False. Use the Date picker below the change point list to pick the dates.
The eagle eyed among you may have spotted that I’ve set the value at the top to ‘False’.
What this is saying is:
- Until March 1st 2017, the value is False.
- Between March 1st 2017 (inclusive and August 31st 2017 (inclusive), the value is ‘True’.
- From September 1st 2017 and after, the value is ‘False’.
So, click ‘OK’ and let’s inspect the effect of our handiwork in the debugger:
There’s a lot more information here and one of the first things you’ll notice is that the total allowance has changed from $5110 to $4386.
If we break down the individual periods, you will see why:
- January 1st – February 28th = 59 days x $10 (Single rate) = $590.
- March 1st – August 31st = 184 days x $14 (Married rate) = $2576.
- September 1st – December 31st = 122 days x $10 = $1220.
$590 + $2576 + $1220 = $4386!
Have a play with different dates and change points and you will find OPA is very good at working this stuff out for you.
OPA also offers a way to visualize this data. Right click the ‘the daily allowance for the citizen’ attribute and select ‘Show in Temporal Visualization’:
A new tab will appear top left named ‘Temporal Visualization’. If you click it, you will see:
This visualization confirms that we start off with $10/day, changing to $14/day from March 1st and changing back to $10/day on September 1st.
Time to complicate things a little by adding another variable to the mix in the shape of the daily income.
Let’s assume that the citizen started 2017 with a daily income of $150. Then later in the year the income rose to $250 and later yet, the income dropped to $180.
In order to deal with this new variable, we will change the rule that calculates the daily allowance to include the daily income for the citizen:
Remember that OPA will evaluate top down, so first it will check to see if the person is married and whether the daily income is less than $200. If this is false, it will check to see if the income is less than $200 and finally, if the citizen is not married and the daily income is greater or equal to $200, the ‘otherwise’ clause will apply.
Make sure the updated rule validates by pressing the ‘Validate’ button.
Now let’s start a debug session and have a look at the outcomes.
Start your debug session and navigate to the ‘data’ tab.
Supply the exact same values as the first example, making sure to set up the change points correctly.
Fun fact: Chances are that OPA still has your previous values in memory, saving you the need to re-enter them!
Check to see that you’re still getting the correct values.
You should see something like this:
Let’s set the value and change points for the daily income:
Click ‘OK’ and inspect the values in the data screen:
As you can see, the total allowance has now been set to $1926 (down from $4386).
We can have a look at what’s been happening in the Temporal Visualization tab.
Make sure the following attributes are shown by going to the debug data tab and right-clicking and selecting ‘Show in Temporal Visualization‘:
- the daily income for the citizen
- the citizen is married
- the daily allowance for the citizen
Go to the ‘Temporal Visualization’ tab. You should see something like this:
As you can see, there’s quite a bit going on here and the daily allowance for the citizen will vary based on marital status and income.
What you will hopefully be able to see is that, when it comes to dealing with changing circumstances, things can get quite complicated quite quickly. In the example we only dealt with two variables but throw in more variables and working out the right amounts would become very complex! Utilizing the out-of-the-box OPA temporal reasoning functionality allows you to manage the complexity of dealing with changing circumstances over time.
More information on Temporal Reasoning can be found in the OPA documentation:
or in the Function Reference:
Finally for those who were wondering, the daily amount that the user is entitled to on June 26th is…
Thanks to Evert for his time and excellent article abut Time Based Reasoning. Readers who what to look at more Time Based Reasoning articles can search here.
Until the next time. If you want to write for the OPA Hub Website, reach out via our Contact Page.