Analysis Calculations

Calculations are a powerful tool in SENAITE to define Analysis Services that take no manual input, but are calculated out of either user-defined parameters (Interim fields) or Results of other Analyses.

During this guide we created an Analysis Service for Total Hardness. However, we did not specify a calculation so far, but would like to be it a sum of the Results from the Calcium and Magnesium Analyses.

Add Calculations

Navigate to the LIMS Setup by clicking the ⚙️ button in the upper right corner and then on the Calculations tile.

Enter the following values in the add form:

• Title: Total Hardness
• Description: Calculate the total hardness of Water based on the Calcium and Magnesium Results
• Calculation Formula [Ca] + [Mg]

☝️Note: You can use any valid Python Expression in the Calculation Formula

Click the Save button when you are done.

☝️Note: The calculation formula references the Keywords of the Analysis Services we defined in the Quickstart section earlier. Selecting a meaningful Analysis Service Keyword is therefore from absolute importance, since changing it later will break existing Calculations!

🤓 Pro-Tip: Calculations also understand a selected set of Python Builtins like min, max, round, pow etc.

Using the calculation in an Analysis Service

Next we need to hook the calculation to the Analysis Service. Navigate to the LIMS Setup and chose the Analysis Services tile. Select the Total Hardness service from the listing and click on the Edit tab.

Navigate to the Method tab and deselect the option Use the Default Calculation of Method. The Calculation selection should then be automatically filled with our new created calculation. Press the Save button when you are done.

Applying an Analysis with a Calculation to a Sample

As already mentioned in the Sample Analyses section, our change in the Analysis Service for Total Hardness does not affect any existing Analyses in our Samples.

Consequently, we must either create a new Sample with the Total Hardness Analysis, e.g. by copying an existing one, or remove and re-add this Analysis from an existing Sample .

Here we are going to create a new Sample by copying an existing one and save the copied values without any changes and receive it afterwards.

The Manage Results listing looks almost similar to the previous ones, but has the Results field of the Total Hardness Analysis greyed out, so that you can not introduce their a manual result anymore.

However, the Calcium and Magnesium Analyses still take manual Results and we can test our Calculation by entering the following values for them:

• Calcium: 9.1
• Magnesium: 9.5

Since we defined the formula as [Ca] + [Mg], we expect for the Total Hardness a Result of 18.6.

The Calculation for Total Hardness got executed after both dependent Analyses were saved and the final Result was marked for submission automatically.

Calculation Versioning

The same behavior like for Analysis Services applies also for Calculations, so that changes in the Calculation does not affect any of the Analysis created with prior versions of the Calculation.

To demonstrate this, we are going to change the Formula of our Total Hardness Calculation and introduce a new parameter (Interim) to our formula:

Navigate to the LIMS Setup and edit the prior created Calculation to enter the following values:

• Calculation Interim Fields:
  • Keyword: factor
  • Title: Factor
  • Default value: 1
• Calculation Formula: ([Ca] + [Mg]) * [factor]

Press the Save button when you are done.

☝️Note: User-defined parameters (Interim fields) also introduce Keywords that can be referenced in Calculation Formulas like the keywords of Analysis Services. Thus, they are checked for uniqueness in the system.

Navigate back to the prior created Sample and click on the blue 🛈 Button next to the Total Hardness Analysis to view the details of the Analysis.

As you can see in the Calculation section of the displayed popup, the formula still references the initial version ([Ca] + [Mg]) and it has not been changed for this Sample. This mechanism ensures pre-existing tests won't change, even after modifying the electronic records they are based on. Therefore, this guarantees the integrity of the data, that is required for compliance with ISO 17025.

However, creating a copy of this Sample uses the new Formula.

The new created Sample displays now also the calculation parameter (Interim field) we introduced earlier. Clicking again on the blue 🛈 Button next to the Total Hardness Analysis reveals the new version of the Calculation with the new Formula ([Ca] + [Mg] * [factor].

External Calculations

Using Python Expressions and Python Builtins inside might be sometimes not enough for your Calculation and you need to do more complex numeric computations.

The SENAITE Calculation machinery let you therefore import your own modules with external functions to even use external libraries like SciPy or NumPy.

Create a file called calculations.py and put it somewhere in the PYTHONPATH on your SENAITE Server. For simplicity, we simply put it directly into the site-packages directory of the used Python interpreter.

Use this command to find out where the site-packages directory is located on your server: python -c "import site; print(site.getsitepackages())"

Add the following contents into calculations.py:

def total_hardness(a, b, factor=1):
   return float(a + b) * factor

☝️Note: You need to restart your SENAITE instances for this new module to be imported!

Navigate to the prior created calculation and enter the following values:

• Additional Python Libraries:
  • Module: calculations
  • Function: total_hardness
• Calculation Formula total_hardness([Ca], [Mg], factor=[factor])

Copy now one of the previous Samples to a new one to use the new Calculation Formula. Also receive the Sample to be able to introduce new Results.

Click again on the blue 🛈 Button next to the Total Hardness Analysis to verify that the new Formula is set to total_hardness([Ca], [Mg], factor=[factor]).

Introduce now some Results for Calcium, Magnesium and the Factor parameter.

Congratulations 🙌 you successfully created your first Calculation in SENAITE and learned how to import external modules for complex computations.