# Formulation

## Specs

| Label                     | Value                         |
| ------------------------- | ----------------------------- |
| **Version**               | 0.1.0 (updated on 2026-03-13) |
| **Developer**             | Labii Inc.                    |
| **Type**                  | Section                       |
| **Support Configuration** | Yes                           |

## Overview

The Formulation widget streamlines the preparation of laboratory reagent mixtures by enabling researchers to define source materials, specify amounts, and automatically calculate target quantities based on configurable ratios. It's particularly useful for preparing PCR reactions, buffer solutions, growth media, and other formulations where precise reagent ratios are critical. This widget seamlessly integrates with Labii's inventory management system by automatically creating consumption records, ensuring accurate tracking of material usage and stock levels.

## Use Cases

* **PCR Reaction Preparation**: Define master mix components with their concentrations and automatically calculate amounts needed for target reaction volumes
* **Buffer Solution Formulation**: Prepare buffer solutions by specifying stock concentrations and calculating the required volumes for desired final concentrations
* **Growth Media Preparation**: Create culture media formulations with multiple components and track reagent consumption for inventory management
* **Standard Solution Preparation**: Formulate standard solutions for analytical procedures with precise concentration calculations
* **Batch Formulation**: Prepare multiple reactions or solutions simultaneously with consistent reagent ratios across all samples
* **Inventory Integration**: Automatically generate consumption records for all source materials used in formulations, maintaining accurate inventory levels

## Interface

### Read-only View

The read-only view presents formulation data in a clean, tabular format that provides a comprehensive overview of all formulation components. Each row represents a single source material with its associated information.

<figure><img src="https://3607108856-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LHVg57XIRcjV-Vbubtn%2Fuploads%2F9NaWVcAe9dLG1InhTFum%2Fwidget-section-formulation.webp?alt=media&#x26;token=be74eca7-0f1a-4b4c-a553-e31705b7e567" alt=""><figcaption></figcaption></figure>

**Key features of the read-only view:**

* **Formulation Table**: Displays all added source materials with their configured fields
* **Base Amount Display**: Shows the base amount and unit for each source material
* **Target Amount Display**: Presents calculated target amounts based on formulation settings
* **Notes Column**: Displays any additional notes or comments for each formulation item
* **Consumption Status**: Indicates whether consumption records have been created for each source

The structured table format allows researchers to quickly review all formulation components, verify amounts, and confirm that calculations align with experimental requirements.

### Edit View

The edit view provides an interactive interface for building and managing formulations. Users can add new source materials, configure amounts, and generate consumption records with simple button clicks.

**Key capabilities of the edit view:**

* **Add Formulation Button**: Opens a modal form for adding new source materials to the formulation
* **Formulation Table**: Interactive table showing all formulation components with action buttons
* **Target Amount Calculation**: Automatically calculates and displays target amounts based on configured settings
* **Individual Consumption**: "Add Consumption" button next to each formulation item for creating individual consumption records
* **Bulk Consumption**: "Add Consumption for All" button enables one-click creation of consumption records for all formulation items
* **Edit/Delete Actions**: Modify or remove formulation items as needed
* **Real-time Calculation**: Target amounts update automatically when formulation settings change

The modal form for adding formulations includes fields for source selection, displayed field configuration, base amount specification, unit selection, and notes entry.

## Configuration

### Initial Setup

{% stepper %}
{% step %}
Navigate to the **Widget Settings** by clicking the Edit button
{% endstep %}

{% step %}
Configure **Consumption Settings** to link with your inventory management system:

* **Consumption Table**: Select the table where consumption records will be stored
* **Experiment Column**: Choose the column that references the experiment
* **Source Column**: Select the column that stores the source material reference
* **Amount Column**: Choose the column for recording consumed amounts
* **Unit Column**: Select the column for amount units
  {% endstep %}

{% step %}
Configure **Formulation Settings** to define calculation parameters:

* **Target Amount**: Specify the target amount value for the formulation
* **Base Amount**: Enter the amount value of the source used as the base for calculating target amount
* **Unit**: Select the unit of measurement for the formulation
  {% endstep %}

{% step %}
Click **Save** to apply the configuration
{% endstep %}
{% endstepper %}

{% hint style="info" %}
The widget uses the base amount and target amount ratio to automatically calculate the required amount for each source material in your formulation.
{% endhint %}

### Required Settings

#### Consumption Settings

* **Consumption Table**: The ForeignKey field pointing to the consumption table where material usage will be tracked. This integration ensures that all formulation activities are reflected in your inventory system.
* **Experiment Column**: Column that links consumption records to the specific experiment or procedure. Essential for maintaining experimental traceability.
* **Source Column**: Column that references the source material being consumed. Connects formulation items to your inventory records.
* **Amount Column**: Column where the consumed amount is recorded. Critical for accurate inventory depletion calculations.
* **Unit Column**: Column for storing the measurement unit. Ensures consistency in amount reporting and inventory tracking.

#### Formulation Settings

* **Target Amount**: The target amount value for the formulation (e.g., 20 for a 20 µL PCR reaction). This value determines the scale of your formulation.
* **Base Amount**: The amount value of the source used as the base calculation reference. The widget calculates target amounts using the formula: (Target Amount / Base Amount) × Source Base Amount.
* **Unit**: The unit of measurement applied to the formulation (e.g., µL, mL, mg). Must be compatible with your source material units.

{% hint style="warning" %}
Ensure that the consumption table structure includes all required columns before configuring the widget. Missing columns will prevent consumption record creation.
{% endhint %}

### Add Formulation Form

When adding formulation items, the modal form presents these configuration options:

* **Source**: Select the source material or sample from your inventory. This field typically includes an autocomplete search for easy location of materials.
* **Fields to Display**: Choose which fields from the source record should be displayed in the formulation table. This allows you to show relevant information such as concentration, lot number, or expiration date.
* **Base Amount**: Enter the amount value of this source used as the base for calculating the target amount. This represents the reference amount from which target amounts are calculated.
* **Unit**: Specify the unit of measurement for this source material (e.g., µL, mL, µM, mg/mL).
* **Notes**: Add any additional notes or comments about this formulation item, such as handling instructions or special considerations.

{% stepper %}
{% step %}
Click the **Add Formulation** button in the widget edit view
{% endstep %}

{% step %}
In the modal form, search and select your **Source** material
{% endstep %}

{% step %}
Choose **Fields to Display** to show relevant source information in the table
{% endstep %}

{% step %}
Enter the **Base Amount** and select the appropriate **Unit**
{% endstep %}

{% step %}
Add any relevant **Notes** for documentation purposes
{% endstep %}

{% step %}
Click **Save** to add the formulation item to the table
{% endstep %}
{% endstepper %}

The widget automatically calculates the target amount based on your formulation settings upon saving.

### Advanced Configuration

For complex formulations requiring multiple calculation bases or mixed units:

{% stepper %}
{% step %}
Configure different base amounts for individual source materials to accommodate varying stock concentrations
{% endstep %}

{% step %}
Use the Notes field to document calculation rationale or special dilution factors for traceability
{% endstep %}

{% step %}
Set up multiple formulation widgets within the same section for multi-step preparation procedures
{% endstep %}
{% endstepper %}

{% hint style="success" %}
For formulations with multiple stages (e.g., preparing a master mix, then aliquoting), consider using separate formulation widgets for each stage to maintain clear documentation of each step.
{% endhint %}

## Additional Functions

### Automatic Target Amount Calculation

Once formulation items are added, the widget automatically calculates target amounts based on your configured formulation settings. The calculation uses the formula:

**Target Amount = (Formulation Target Amount ÷ Formulation Base Amount) × Source Base Amount**

This ensures consistent scaling across all components in your formulation.

{% hint style="info" %}
Target amounts update automatically when you modify formulation settings. This allows quick recalculation for different batch sizes without re-entering individual source amounts.
{% endhint %}

### Individual Consumption Creation

For each formulation item in the table, an **Add Consumption** button enables individual consumption record creation.

{% stepper %}
{% step %}
Review the calculated target amount for the specific formulation item
{% endstep %}

{% step %}
Click the **Add Consumption** button located to the right of the formulation row
{% endstep %}

{% step %}
The widget creates a consumption record in the configured consumption table with:

* Source reference from the formulation item
* Experiment reference from the current record
* Amount equal to the calculated target amount
* Unit from the formulation settings
  {% endstep %}

{% step %}
A confirmation indicator appears showing the consumption record was created successfully
{% endstep %}
{% endstepper %}

This function is useful when you need to selectively create consumption records, such as when some materials were not actually used or when verifying amounts before committing to inventory depletion.

### Bulk Consumption Creation

The **Add Consumption for All** button streamlines the process of creating consumption records for all formulation items simultaneously.

{% stepper %}
{% step %}
Review all formulation items and verify that calculated target amounts are correct
{% endstep %}

{% step %}
Click the **Add Consumption for All** button in the widget interface
{% endstep %}

{% step %}
The widget processes all formulation items and creates individual consumption records for each source material
{% endstep %}

{% step %}
Confirmation messages display showing the number of consumption records created
{% endstep %}

{% step %}
Verify that all consumption records appear in your consumption table with correct amounts
{% endstep %}
{% endstepper %}

{% hint style="success" %}
Using the bulk consumption creation feature ensures consistent timestamp and metadata across all consumption records for a single formulation event, improving audit trail clarity.
{% endhint %}

### Edit and Delete Formulation Items

Modify existing formulation items or remove them as needed:

* **Edit**: Click the edit icon to modify source, base amount, unit, or notes
* **Delete**: Click the delete icon to remove a formulation item from the table

Changes to formulation items automatically recalculate target amounts.

### Formulation Pre-planning

The widget serves as an effective planning tool before executing laboratory procedures:

{% stepper %}
{% step %}
Add all required reagents to the formulation with their base amounts
{% endstep %}

{% step %}
Adjust the target amount in formulation settings to match your desired batch size
{% endstep %}

{% step %}
Review calculated target amounts to ensure feasibility with available stock
{% endstep %}

{% step %}
Print or export the formulation table as a preparation checklist
{% endstep %}

{% step %}
Execute the formulation following the calculated amounts
{% endstep %}

{% step %}
Create consumption records after confirming successful preparation
{% endstep %}
{% endstepper %}

This workflow enables verification of material availability and amount feasibility before beginning actual laboratory work.

### Integration with Inventory Management

Consumption records created by the widget automatically integrate with Labii's inventory management system:

* **Real-time Stock Updates**: Consumption records trigger automatic inventory depletion
* **Batch Tracking**: Links consumption to specific source batches for lot traceability
* **Usage Analytics**: Consumption data feeds into usage reports and reorder calculations
* **Audit Compliance**: Creates comprehensive audit trail of material usage for regulatory compliance

## Best Practices

### Data Organization

* **Consistent Naming**: Use standardized names for formulations to improve searchability across experiments
* **Detailed Notes**: Document any deviations from standard procedures, special handling requirements, or observations in the Notes field
* **Source Selection**: Always select the specific batch or lot of source material rather than generic inventory items for better traceability
* **Field Display Configuration**: Choose to display critical information such as concentration, lot number, and expiration date in the formulation table

### Calculation Accuracy

* **Unit Consistency**: Ensure units are consistent between source materials and formulation settings (e.g., if mixing volumes, use µL or mL consistently)
* **Base Amount Verification**: Double-check base amounts before adding formulation items, as these directly impact target amount calculations
* **Concentration Considerations**: When working with stock solutions, use the Notes field to document concentration calculations or dilution factors
* **Rounding**: Be aware of rounding in calculated target amounts; for critical applications, verify calculations before proceeding

{% hint style="success" %}
For PCR reactions and other high-precision applications, configure formulation settings to calculate amounts with appropriate precision for your pipetting capabilities (e.g., 0.5 µL increments).
{% endhint %}

### Workflow Efficiency

* **Template Formulations**: Create standard formulations for commonly used reagent mixtures and save them as templates for quick reuse
* **Batch Preparation**: Use the bulk consumption feature for routine formulations to minimize data entry time
* **Sequential Planning**: Add all formulation items before creating consumption records to allow final review and adjustments
* **Multi-stage Procedures**: For complex preparations, use multiple formulation widgets to document each stage separately

### Inventory Management Integration

* **Timely Consumption Creation**: Create consumption records immediately after using materials to maintain accurate real-time inventory levels
* **Pre-check Availability**: Review formulation requirements against current inventory before beginning preparations to avoid mid-procedure material shortage
* **Consumption Verification**: Periodically audit consumption records against actual material usage to identify discrepancies
* **Batch Traceability**: Always link consumption to specific source batches for complete lot traceability in regulated environments

### Compliance and Documentation

* **Complete Documentation**: Fill in all relevant fields including notes to create a comprehensive record for regulatory audits
* **Review Before Execution**: Verify all formulation items and calculated amounts before creating consumption records, as these become part of the permanent audit trail
* **Electronic Signatures**: For GLP/GMP environments, ensure formulation records are reviewed and electronically signed according to your procedures
* **Archive Standards**: Retain formulation records according to your organization's data retention policies and regulatory requirements

{% hint style="warning" %}
Once consumption records are created, they become part of the audit trail and typically cannot be deleted. Ensure accuracy before clicking "Add Consumption" buttons to avoid audit trail complications.
{% endhint %}

### Common Pitfalls to Avoid

* **Avoid**: Creating consumption records before verifying calculated amounts are correct and feasible
* **Instead**: Always review the formulation table and calculated target amounts before using consumption creation features
* **Avoid**: Mixing incompatible units (e.g., volume for one source and mass for another) without clear documentation
* **Instead**: Maintain unit consistency or document conversion factors clearly in the Notes field
* **Avoid**: Using generic source references that don't specify batch or lot information
* **Instead**: Select specific inventory items with complete batch/lot traceability
* **Avoid**: Forgetting to create consumption records after completing formulations
* **Instead**: Make consumption record creation the final step of your formulation workflow

### Performance Optimization

* **Limit Display Fields**: Select only essential fields to display for source materials to improve table loading performance
* **Batch Size Considerations**: For very large formulations (>50 items), consider breaking into multiple smaller formulation widgets
* **Data Management**: Periodically archive old formulation records to maintain optimal widget performance

## Related Widgets

* [**Formulate**](https://docs.labii.com/widgets/section-widgets/data-analysis/formulate): Alternative option for optimization-based formulations. Choose this widget if you need to optimize ingredient combinations based on constraints and objectives using linear programming algorithms.
* [**Calculation**](https://github.com/Labii/labii-gitbook-docs/blob/gitbook/widgets/section-widgets/data-analysis/calculation.md): Simpler option for basic mathematical calculations. Use this widget if you only need to perform calculations without inventory integration.

### Integration Scenarios

* **PCR Workflow**: Combine Formulation + Rich Text + Image Gallery for complete PCR reaction documentation
* **Buffer Preparation**: Use Formulation + Table (for buffer recipes) + Inventory Management for standardized buffer preparation and tracking
* **Media Preparation**: Integrate Formulation + Protocol + Consumption tracking for batch media preparation with full traceability
* **Quality Control**: Combine Formulation + Calculation + Results widgets for formulation validation and QC testing documentation
* **Batch Production**: Use multiple Formulation widgets + Inventory Management + Workflow automation for scaled production workflows