# LIMS Calculations

Veeva LIMS allows you to configure *Test Definition Results* as calculated results, populating the result value at runtime according to a formula you define in the result definition.

These calculation formulas can reference other results in the same *Test Definition*, results from other *Test Definitions*, or a centralized list of calculation constants. Design Data Admins accomplish this by first adding *Calculation Variables* to the result definition, targeting them to other results or constants accordingly, and then referencing them in the calculation formula.

For example, suppose that a pH test is run in triplicate:

ph Result1: 6.5

ph Result2: 6.0

ph Result3: 6.2

ph Average (rounded to 1 decimal place): 6.2

The calculation formula might be  `Average($BVR1, $BVR2, $BVR3)` where `BV` stands for a Basic Variable that was created for each pH Result.

## **Setting Up Calculated Results**

To add a calculated *Test Definition Result*:

1. In a *Test Definition* object record create a new *Test Definition Result* of type **Numeric Result**.
2. In the **Expected Data Entry Method** field, select **Calculation**.
3. Fill in the other fields as appropriate for the calculated result.
4. Click **Save**.

To add variables to a calculated *Test Definition Result*:

1. In the *Variables* section of the *Test Definition Result* record detail page, click **Create**.
2. Select a type from the drop-down:
    * **Basic Variable**: The variable's value is drawn from another result within the same Test Definition.
    * **Cross-Test Variable**: The variable's value is drawn from a different *Test Definition*.
    * **Constant Variable**: The variable's value  is drawn from your Vault's repository of established constants.
    * **Aggregate Variable**: Multiple results may be located and passed into the calculation.
3. Enter a **Name**. The *Name* value for a variable can only be made of letters and numbers, and cannot contain spaces.
4. If you are creating a *Basic Variable*, select a **Target Test Definition** and then a **Target Test Definition Result**.
5. If you are creating a *Cross-Test Variable* or an *Aggregate Variable*, select a **Target Test Definition**, **Target Test Definition Result**, and **Scope**.
6. If you are creating a *Constant Variable*, select a **Target Constant**.
7. Click **Save**.

The target result of a variable is identified using the *Trace ID* of the *Test Definition* and *Test Definition Result*. Once you have created your variables, you can define the formula for the calculation.


### Defining a LIMS Calculation Formula

LIMS calculation formulas follow standard [Vault formula construction](/en/lr/42857/)
 with the following additions:

* Variable names are always preceded by a dollar sign (`$`). Typing $ will cause the formula builder to display all available variables for quick insertion.
* You can click the **Variables** tab to see all available variables.
* Two Log functions are available to facilitate logarithmic calculations:
  * `log(value, base_number)`: calculates the log base `[base_number]` of `[value]`.
  * `ln(value)`: Calculates the natural log (base e) of `[value]`.

For example, the formula `( $A1 - $B2 ) / $C3` will divide the difference of the variable values `A1` and `B2` by variable value `C3`.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: Ensure that you leave a space after the variable name so Veeva LIMS can distinguish a variable from other characters in the formula.</p>
    </div>
  </div>
</div>



## **Calculation Constants**

Veeva LIMS allows you to manage a central library of constants for use in *Calculation Variables*. *Calculation Constant* records contain one or more *Constant Value* records, allowing calculation formulas to refer to the *Calculation Constant* and for Veeva LIMS to automatically select the appropriate *Constant Value* according to the type of *Constant* (*Global* or *Material*) and *Material* on the *Batch*.

To create a *Lab Calculation Constant*:

1. Navigate to a **Lab Calculation Constants** object tab.
2. Click **Create**.
3. Enter a **Name**.
4. Select a **Constant Type**:
    * **Global**: Allows a single *Constant Value*.
    * **Material**: Allows you to define a *Constant Value* per *Material*.
5. Click **Save**.

Once you have created your constant, add the appropriate constant value or values.

### Constant Values

Each *Lab Calculation Constant* must contain at least one (1) *Constant Value* in order to be used in a *Calculation Variable*. To create a *Constant Value*:

1. In the *Constant Value* section of a *Lab Calculation Constant* record detail page, click **Create**.
2. Enter a **Name**.
3. Enter a **Value**.
4. If you are creating a value for a *Material* constant, select a **Material** record to associate it with.
5. Click **Save**.

Global constants only contain a single *Constant Value*. Material constants can contain multiple values, but each must be associated with a specific *Material* record.

#### About Constant Value Versions

To ensure traceability, Veeva LIMS automatically creates *Constant Value Version* records every time you edit a *Constant Value* record. When Veeva LIMS selects a constant for a *Lab Test Result Variable*, it uses the latest *Constant Value Version* when passing the value into the result calculation. Because *Lab Test Result Variables* at *Lab Test* creation target specific *Lab Calculation Constant Value Version* records, you can freely update the *Value* field on the *Constant Value* record without affecting currently running *Lab Tests*.

## **About Variable Dependency in Calculated Lab Results**

When Veeva LIMS creates *Lab Results* from *Test Definition Results*, it also creates *Lab Test Result Variables* based on the variables attached to each *Test Definition Result*. Those *Lab Test Result Variables* target specific *Lab Results* (in the same *Lab Test* or from another *Lab Test*) or *Lab Calculation Constants* that contain the values needed for the calculation.

Because *Lab Results* are created when the Generate Tests action is run, which may be at any time, it's possible that a cross-test *Lab Test Result Variable* is created before the *Lab Result* it's targeting has been created. In that situation, Veeva LIMS creates the *Lab Test Result Variable*, and when the necessary *Lab Result* is eventually created, Veeva LIMS will target the *Lab Test Result Variable* accordingly.

## **About Calculations in Test Execution**

Calculated result values are generated when a *Lab Test* is completed. When generating calculated result values, Veeva LIMS performs the following:

1. Validates the calculation formula.
2. Calculates the result.
3. Evaluates the result against any existing specification criteria.

If Veeva LIMS cannot resolve the calculation, or enter the value into the *Lab Result*, the system captures the errors in the *Lab Result*'s *Save Errors* field.

If a *Lab Test* is marked as invalid, none of its *Lab Results* are included in calculations.

# **Related Permissions**

To view and manage calculation formulas, a user needs a permission set with *View* access to the *Calculation Formula* object control permission on the *Test Definition Result* object and *Create*, *Edit*, and *Delete* permissions on the *Test Definition Result* object.