Rules
Last updated
Last updated
Rules contain the subject matter logic that describes how new facts can be inferred.
They specify the conditions under which two concept instances can be linked by a relationship to form a new fact.
E.g. the graph might have a relationship of (Account) > has a risk status > (Risk status)
A rule would be required that describes how the risk status can be inferred based on available data, so the reasoning engine can determine that:
Account 123 > has a risk status > Low and,
Account 789 > has a risk status > High
Rules are created on a relationship and therefore they are accessed via the relationship configuration panel within the Studio.
An existing rule can be viewed or edited by selecting it in the list or a new rule created by clicking ‘Add rule’.
The rule will default to having no predefined value for the subject or object and a certainty of 100, but these can be easily modified if the rule needs adapting.
Clicking Add Condition will allow a condition to be created. The relationship must be selected first. Once selected, the subject and object of that relationship will default to a variable. This default is based on:
the concept shares the subject of the rule (represented with %S)
the concept shares the object of the rule (represented by %O) or
the concept shares neither and will be assigned a variable name based on the concept name (e.g. Person will be %PERSON)
If a specific value is required, rather than a variable, the subject or object can be changed. Based on the data type of the concept you will either be presented with a dropdown list containing instances, a date picker or a number field.
You are not limited to using the default of %concept to name variables. By typing directly in the field you can give a variable any name you chose provided it starts with %. You can have multiple variables of the same concept type within a rule (i.e. %customer and %user might both refer to Person concepts).
Expressions are functions that allow you to compare or transform data during a rule. For example you can write expressions to:
check values are greater or less than other values
perform a range of calculations
compare dates and times
count, sum, concatenate values
The expressions list page provides information of all functions that are available to use when writing expressions.
Clicking Add expression will allow an expression to be created. Within the expression field, pressing ctrl+space opens the expression auto-complete where snippets can be searched to aid in writing expressions.
If the expression generates a value (i.e. a calculation was performed) and this needs be used elsewhere in the rule, this can be assigned to a value. You may either want to assign it to a variable to use in another condition or expression (i.e. typing %VARIABLE) or if the output of the expression is what the rule is trying to answer it can be assigned to %O to be used as the object of the rule.
Weight is used to express which conditions in a rule are more relevant or important, which impacts the certainty of the fact created by the rule.
The default weight is 100, but can be adjusted to any value that is not a negative number.
Setting the weight to zero means the condition may be required by the rule, but that it has no impact on the certainty that is calculated.
Weights are relative to each other. This means a rule with 3 conditions with a default weight of 100 are regarded as equally important for that rule. These could be adjusted to 10, 5 and 0, which shows one condition is twice as important to another, whilst the 3rd will not impact the certainty.
Behaviour declares whether a condition in a rule is mandatory or optional for the rule to be met. This defaults to mandatory, but you can toggle the condition to be optional with the optional toggle switch.
All mandatory conditions must be satisfied for the rule to be met. Optional conditions can add certainty to a fact, but are not necessary for the rule to be met.
For example, it might be mandatory that a person resides in the UK for a loan to be approved, but optional that they are in full-time employment.
The rule and its conditions have advanced settings to further refine them.
If you want to prescribe the order in which conditions are processed, this can be set by the condition ordering property. There are three options:
If the order of conditions is important, they can be reordered by clicking and dragging a condition to a new location.
By default, Rainbird will only generate a fact if the certainty is 20% or higher. This minimum can be adjusted with this property. This value must be equal to or lower than the certainty of the rule. E.g. if the rule has a certainty of 60% the minimum rule certainty cannot be 61%.
To provide more context or a more user-friendly explanation to support the evidence you can add evidence text. This can be created for each rule and/or each condition of the rule.
This is set here:
Variables used in the rule can also be used in the evidence text to display contextually relevant data. To do this, enclose the variable within a double curly brace e.g. {{%VARIABLE}}.
This text is included in the evidence data, returned via API to be used as required.
In our evidence tree visualisation we use this alternative explanation instead, as shown below.
Without evidence text
With evidence text
For more advanced explanations, the Knowledge Map can be traversed to acquire additional data to display. For example if a fact existed that Spain > is in continent > Europe and you wanted to the evidence text to read Spain, Europe then you can declare this using dot notation in the following way.
When creating or updating a rule various checks are made to ensure it is valid. Below is a list of some of the validation errors that might be shown and a further explanation about what they mean:
| Error message | Description |
|---|---|
Default
The order of conditions is automatically determined at runtime and has the highest chance of a rule succeeding.
Top Down
The conditions are processed as they are ordered in the rule (top to bottom). It will skip over conditions that it cannot meet, but return to them to retry before the processing of the rule is completed.
Top Down Strict
The conditions are processed as they are ordered in the rule (top to bottom), but if a mandatory condition cannot be met, the rule will immediately fail.
Certainty must be more than or equal to the minimum rule certainty.
You need to ensure the minimum rule certainty, within the advanced section of the rules panel, is the same as or lower than the certainty of the rule.
A rule must contain at least 1 condition or expression.
Start adding conditions or expressions before trying to create your rule.
If you are trying to create a fact by setting a value on the subject and object, you need to do this by opening the subject concept, then the instance. The fact can be set here.
The total of all condition weights must be greater than 0.
The weights on all of the conditions are set to zero. They must add up to a minimum of one.
The relationship ‘[relationship name]’ expects the concept of [concept name]. The variable used ([%variable_name]) is ‘[concept name]’.
This error will be shown when the variable mentioned has already been used in the same rule to represent a different concept.
Please carefully check your concepts and relationships and the variables you are using the represent them.
