Creating Project Property equations

Overview

When defining equations it can be helpful to think of two types. Simple equations that involve some arithmetic on several properties, for example a sum of several properties, and ratio equations, that typically define the ratio of two or more properties. You will need to define the details, including units and where relevant ratio types for all input properties, and you also need to define the target units - all ratio equations are assumed to be written in a/b form. You can share your new project property equations with colleagues whenever you export them with any templates. Project properties are designed to enable you to create your own properties and can be assigned new equations to help you calculate new ratios or other quantities. Equations can be as complex as you wish, and can take in other project properties as inputs, and will auto-evaluate.

Usage: Data --> New project property... Add equation for property...

How to use in practice

Creating simple equations

First you need to define the new property that will be the target of the equation. You will need to consider appropriate units for this target. p:IGI+ has a complete unit system, but will not check that the units are sensible - you need to do this. In general if adding / subtracting properties the units for the result should be the same as the units for the inputs, and if dividing things with the same units the result will be unitless, although for some equations a mass, volume or mol fraction might be appropriate.

To add the equation to the property click on the Add equation for property... link.

This will bring up the equation definition dialogue. This allows you to select a number of properties and combine these in an expression.

In the right hand panel you can search for and select properties, as usual in the system. You can change the unit (and where relevant the ratio) to be used for these input properties. p:IGI+ will take care of all unit conversions as the equation is evaluated (from version 2.3 for ease of use the units and ratios of the inputs will be fixed to the default unit and ratio). You can also define the symbol you want to use for this property when typing the equation. By default you get the property short name, but you can replace this with any name you like.

Clicking the Add button adds this input to the list of input properties on the left and to the equation with an addition. You can remove any properties you don't need using the red cross, or can edit the symbols of properties by clicking on the row and making the change in the right hand panel and selecting the Update button. If you are editing and decide you need to add another new property, notice that the New Input button is now active and can be clicked to return to a blank property selector with which you can add another new variable.

Once you are happy with the inputs you have selected you can start writing the equation. You type the equation as plain text - the equation system will try and parse the text as soon as you pause typing and will tell you whether the equation is valid. There is a blue "i" button for further information on how to write equations - clicking this brings up a window with advice on how to write equations.

Writing equations is designed to work a bit like the way you define equations in Excel, but simpler. Having given the properties symbols you can now use those symbols to write the equation. Let's imagine we have called our properties X, Y and Z for now. Equations can involve:

Operations: + - * / ^
Brackets: ()
Functions: log() ln() exp() sqrt() abs()
Special functions: exists{} use{ A else B}

Equations take the form of expressions which combine the above and symbols for example:

X+Y/100 - this will add X to (Y divided by 100).
(X+Y)/(Z-2) - this will add X to Y, then divide this by (Z minus 2). Note that brackets can be nested to ensure the right order of evaluation.
exp(-Y/100)*ln(Z) - this will calculate the exponent of -Y/100 and then multiply this by the natural logarithm of Z.
X+Y+exists{Z} - this will add X and Y, and if present Z. If Z is missing the exists keyword will replace it by a zero.
use{X else Y}+Z - this will add X to Z if X has a value, if not it will try and add Y to Z.

The exists{} special function allows you do include inputs which might often not be measured, but when they are should be included, but means that if they are missing the equation is still evaluated. When the term inside the exists{} special function is involved in addition or subtraction, if the value is missing it is assumed to be zero, when used in multiplication or division it is assumed to be one.

The use{X else Y} can be used if you prefer to use a particular property when it is available, but if not then another can be substituted. In addition you can use the pre-defined Any properties, which have their own substitution rules which will be used in the equations.

Once you are happy with the equation, and are also happy you have set the target unit for the equation you can press the OK button to add the equation to your new property. Note that for any ratio quantities you should always write the equation as a/b, even if by default you want to see the result as a/(a+b), since you can set the default ratio separately. Writing equations as a/b keeps them compact. When you have pressed OK you will be returned to the project property dialogue, but will notice that it now has an equation being displayed as shown below.

You can still edit the equation by selecting the Add equation for property... link or remove it using the red x. Once you are happy with the project property being created, including the equation, you press the Create button. You might notice a pause in the application at this point, while p:IGI+ updates the database, adds the equation to the equation system (which is a complicated job!) and then evaluates the equation on all possible samples. In large data sets this pause might be quite noticeable.

Note that the creation of project properties and equations can be undone. You can also delete the project properties later if necessary.

From v2.3+ you can edit a project properties equation (Data>Edit project property equation...) which will recalculate the values for the project property.

Advice on writing equations

Writing equations in not simple, but they are powerful. Care must be taken in defining equations. You need to make sure that the unit group you have selected for the property makes sense for the equation you are creating. Note that the default unit you select does not have to be the unit for which you define the equation. For example if you want to create a ratio of e.g. iC5/nC5, but actually want to show it as a normalised % a/(a+b), we suggest you define the equation as iC5/nC5 (a/b) form and have the target unit for the equation be the Euclid (Euc) - that is the non-dimensional natural number. Then in the property definition you define the default unit at %, and the default ratio as a/(a+b). This keeps the equation as simple as possible and uses the units and ratio system to do the conversions to the desired units.

It is also important when writing equations to consider the units for the inputs. Most of the time this will fall out very naturally, but sometimes it can be helpful to use the unit system to convert to sensible units before adding the properties to the equations.

Sharing project properties with equations

When you create new project properties, if you export any templates for artefacts that use these new properties, such as graphs, palettes, pages, then the definitions for the project properties and any associated equations are saved along with the artefacts. This means that you can send colleagues templates for graphs that help interpret the new ratios, with overlays you have added, and when they import your template, this will create the new project property in their project, calculate the values of your new ratio for their data and show their data on the graph you have created. All with the right units.

There is one thing to watch however, and this is a bit technical. When you create a project property you give it a name, however p:IGI+ knows it by using a unique id. If someone else creates an identical property (same name, equation etc) p:IGI+ will give that a different unique id. So that property, so far as p:IGI+ is concerned is not the same thing. Indeed you cannot have two project properties in p:IGI+ with the same name - this is sensible because the name is how you find and identify what that property means - having two with the same name is a bad idea. If you want to share project properties across your organisation we suggest you define these only once, and provide a (e.g. page) template with all these in one place centrally, since at that point everyone will genuinely be using the same properties across your organisation.