Rules

Overview

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:

1. Account 123 > has a risk status > Low and,

2. 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.

Conditions

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

Expressions are functions that allow you to compare or transform data during a rule. For example you can write expressions to:

1. check values are greater or less than other values

2. perform a range of calculations

3. compare dates and times

4. 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

Weight is used to express which conditions in a rule are more relevant or important and this can impact the certainty of the fact created. A conditions weight defaults to 100, this can be adjusted to any value that is not a negative number.

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

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.

Advanced properties

The rule and its conditions have advanced settings to further refine them.

Advanced drawer for rules

Advanced drawer for an individual condition

Condition ordering

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:

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.

If the order of conditions is important, they can be reordered by clicking and dragging a condition to a new location.

Reordering a conditions of a rule

Minimum rule certainty

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%.

Evidence text

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:

Evidence text for the rule and a condition

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.

// Based on the fact that {{%S}} lives in {{%COUNTRY}}, {{%COUNTRY.is in continent}}

Rule validation

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
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 variable [%variable] only appears once. It should be used in at least 2 conditions.	A variable has been set, but this has not been used elsewhere in the rule. If it is not required, the condition or expression can be updated or removed. If it is required, another condition or expression needs to reference it.
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.