Tag Matching
How RuleFour finds variables
Variables in RuleFour, such as those defined by Inputs or Cost Elements, are referred to by their name and associated Tags.
Matching Variables (Tag Matching)
While the primary identifier of a Variable is its name, using Tags to distinguish between Variables enables much more flexibility through reuse and through the use of the structure when locating Variables. When matching a Variable, all the Variables with a matching name are located, then the Tags are used to find the best match, where the variable with the most matching tags is considered the best match.
For example if we want to lookup the distance travelled for a particular truck, we can use a common variable name for Distance Travelled and use a Tag to specify which truck that value corresponds to.
When evaluating a Variable, matches can be either an exact match, a partial match (only some tags match) or a non-match. If there are multiple Tags, then the more Tags that match the stronger the overall match will be. Two out of three is a stronger match than one out of three, and three out of three, or an exact match would be the strongest match. A non-match however, excludes the Variable from further consideration.
Inputs can also be matched by Group, using the group name. In this case only the Group name is used and all Inputs in the Group are considered a match.
Inheriting Tags
When evaluating a Variable used by a Element, the Tags of the Element are used to locate the best match. Similarly when evaluating a derived input, that references a Variable using the Auto Tags Match source type, the Tags of the Input are used to match the variables it references. So, in both cases when evaluating a variable the tags are inherited from the previous element.
Below is a Element which represents the Fuel Costs for a certain truck. The Element is tagged with the Equipment and Organisation lists which also indicate its position in the structure. The tagged values are then inherited by the variables Fuel Cost and Fuel Consumption when they are evaluated.
Looking at the Fuel Consumption Input we can see that no Tags are specified. Instead any unspecified Tags inherit their values from above.
Given the Element above which is tagged with Equipment: Truck 601 when it evaluates the Fuel Consumption Variable its Tags including the Truck 601 Tag are passed down. Therefore the Fuel Consumption Input will use the value Truck 601 for the Equipment Tag when it is evaluated.
When there are also Tags that are specified for an Input they will be combined with the Inherited Tags. In this scenario, if the Fuel Consumption Input also specified a particular piece of Equipment then the explicitly specified tag would take precedence over the inherited Tag. This could be used to model a special piece of equipment that used a different fuel consumption rate while most equipment uses the standard rate.
The Schedule vs Previews
Matching a Variable requires a single best match, so when matching with Tags you'll need to ensure that there is always a single Variable for the result. If there's no single best match this typically indicates an issue with the Model or the Inputs.
Take the following Inputs for example, if you matched these Variables using the name "Number of" and the value "Warehouse" for the department then every variable with the Tag "Warehouse" would match. So it would not be possible to determine which number the user meant to match. In order to get the number of staff for a given type of employee you would need to specify a value for the "Employee Type" Tag.
In the Schedule if there is more than one matching input you will see the error "found too many inputs". However, Input previews will show the first match even if there is a duplicate. This is because it is often useful to see one example, but the exact Tags that will be used by the Schedule will depend on what Tags are inherited as well.
Locating Schedule Elements
Derived Inputs can also be used to lookup Elements as well Inputs.
When selecting Schedule option for Variable Source to locate an Element, specifying a Tag will restrict matches to Elements with that same Tag. For example if the Employee Type was Manager then only Elements tagged with Manager would match. On the other hand, if the Employee Type is (Anything), it implies we do not care what the Employee Type of the Element is, so any value will match.
In the example Derived Input above, because every other tag is set to (Anything), Elements with any values for those tags would be matched regardless of the value of the Tags. Note that if there are mulitple matches they will be summed together.
However, sometimes may want to inherit some tags instead. In this case you should select the (Inherit) option for a Tag to inherit tags from the current context.
Now, the Cost Type Tag will be inherited from the previously evaluated Variable, so we'll be looking for a varaible with taged for "Head Office" and the inherited Cost Type.
Tag inheritance comes in handy when you'd like to create an Element to calculate a margin, or buffer.
Below we're creating a Schedule Element that calculates a cost margin for each truck using the existing Elements used to calculate component costs such as Fuel, Toll and other Costs.
To do this efficiently we'll create a single Derived Input to calculate the truck cost margin. However, we don't want it to match every cost in the Schedule. Only the costs associated to one particular truck; the truck that is being evaluated. So just like we can use Inherit to match the correct input based on a Tags of an Element in the Structure, we can inherit the Tags of the input and use them to lookup an Element.
When the Element "10 Truck 601 Margin" is being evaluated in the context of "Truck 601" the Tag will be carried through and used to select all the Elements with that Tag.
You can use as many levels of Tag inheritance as you like, but there is a limit of 20 levels when a Derived Input references another Derived Input. A chain of Derived Inputs will continue to pass Tags down as each level is evaluated. This allows you to keep the initial context of the original Cost Element until you override it with an explicit Tag or the chain reaches its end.
The real power of Tag Inheritance and Tag Matching comes from using the Structure of your model to drive the calculations. Combined with Templates you can create and modify robust models in less time than ever before.
Last updated
