Batch Design
Batches represent a specific quantity of a given mixture. The
mixture is a virtual entity, i.e. a recipe, used to create a real, physical
batch of material. The design of the Batch, meaning the fields, properties, and naming pattern, is set by default to provide commonly used fields and defaults, but can be edited using
Manage > Edit Batch Design.
For example, batches include fields for tracking expiration date, amount, and units for that amount, making it possible to track inventories and efficiently use materials.
See details in the instructions for creating a sample type design here:
Biologics: Create Samples
Batches
To create a new batch, click
Add above the batches grid, or select
Create > Mixture Batch from any mixture detail page to include that mixture in your batch.
The steps in the batch creation wizard are similar to those in the
mixture wizard.
Details
On the
Details tab, complete all required fields and any option fields desired. If the
Batch Name is not provided, it will be automatically assigned a unique name using the naming pattern for Batches. Hover over the
for any field to see more information.
Click
Next.
Preparation
On the
Ingredients tab, each ingredient row is disabled until you add a
Desired Batch Yield and
Unit. Once selected, the rest of the page will become enabled and populate information.
Enter the exact amounts of which raw materials were used to create the mixture recipe. (If ingredients and/or amounts are unknown, see options
below.) For each raw material, specify a source lot by its id number. An administrator can
enhance the details show to users in this dropdown as described below.
Each ingredient in the recipe may have
one or more source lots of raw material This is useful when you exhaust one lot and need to use a second lot to complete the batch. For example, using 40g of Potassium Phosphate empties a lot, if the next lot contains 45, you would need an additional 15g from another lot to reach the target amount of 100g shown in the following. Add additional lots by clicking
Add raw material for the specific ingredient.
Note that if one or more raw materials are indicated, the option to set an amount or raw material as unknown is no longer available.
You can also add ingredients (or other mixtures) as you register a batch. Click
Add ingredient at the end of the ingredient list.
For each preparation step in the mixture recipe, the user can enter any preparation notes necessary in creating this particular batch. Notes are optional, but can provide helpful guidance if something unusual occurred with the batch.
Once all required fields are filled, the
Next button will become clickable.
Confirmation
The confirmation step allows the user to view the information they have entered. If necessary, they can click back to return to previous tabs to make any updates. Preparation notes are collapsed, but can be expanded by clicking the right-arrow icon.
Click
Finish to register this batch and see the row as entered in the grid.
If multiple raw materials were used, the batch details panel will display material lot numbers and the amounts used.
If additional ingredients were added to the batch, these modifications from the mixture recipe will be noted in a panel:
Amounts and Units
The amount, and units for that amount, are determined from the Batch Yield details provided on the
Preparation tab. Three fields are stored and visible:
- Recipe Amount (RecipeAmount) : The amount, i.e. "Desired Batch Yield". This value is stored as a property on the run that created the batch. Note that this field is not editable as it is not a property of the batch.
- Recipe Amount Units (Units and also RawUnits): The units value for the Recipe Amount field.
- Recipe Actual Amount (StoredAmount and also RawAmount): The "Actual Batch Yield".
Note that if you have existing data prior to the addition of the Amount and Units default fields in version 23.4, the combined amount-with-units field will be parsed into the two fields. If we cannot parse that text field (such as in a case where the units value is not supported) the two fields will be left blank and need to be manually populated.
Registering Batches with Unknowns
When registering batches, the Ingredients step includes the option to mark:
- all materials as unknown
- individual raw materials as unknown
- individual amounts as unknown
This is useful when adding vendor supplied batches to the registry, where you may not know specific details about the vendor's proprietary materials and/or amounts.
Note the button
Show unknown options. When clicked, the UI reveals "Unknown" checkboxes underneath each row's amount and raw material input. Selecting
Unknown will then disable the individual input.
To disable all material and amount inputs, click to set the slider for
Materials/Ingredient Source to
Unknown.
Confirmation warnings are provided if the user provides incomplete values and an 'unknown' box is not ticked.
Once entered into the registry, the unknown factors are reflected in the user interface.
Bulk Registration of Batches That Include Unknowns
In bulk registration of Batches, some fields support the text "unknown" on import. For details, see
Bulk Registration of Entities.
Aliquot Batches
Instead of having to register sub-portions of mixture batches in advance, you can create large batches, then later create aliquots from them. You can specify the
Aliquot Naming Pattern by
editing the Mixture Batch Design. The default name of an aliquot is the name of the parent batch, followed by a dash and a counter for that parent. Learn more here:
Biologics: Create SamplesSelect one or more Batches from the grid and choose
Derive > Aliquot Selected.
In the popup, as for
creating sample aliquots, enter the number of
Aliquots per parent to create, then click
Go to Mixture Batch Creation Grid. Aliquots of mixture batches will be shown in the same grid as the original batch(es). Include the
IsAliquot column in your grid view if you want to be able to filter for aliquots.
Add Detail to "Raw Materials Used" Dropdown
The "Name" of a Raw Material is it's generated ID; these are not particularly helpful to users selecting the raw materials for a batch. By customizing raw materials with a
lookup view, administrators can provide their users with the necessary details when they select from the dropdown.
- To customize the "Raw Materials Used" dropdown, first switch to LabKey Server by selecting > LabKey Server > [Name of your Biologics home project].
- Open the schema browser via: (Admin) > Go To Module > Query.
- Select the samples schema, RawMaterials table.
- Click Edit Metadata.
- Scroll down and click Edit Source.
- On the XML Metadata tab, add the following:
<tables xmlns="http://labkey.org/data/xml">
<table tableName="RawMaterials" tableDbType="NOT_IN_DB">
<columns>
<column columnName="Name">
<shownInLookupView>true</shownInLookupView>
</column>
<column columnName="lotNumber">
<shownInLookupView>true</shownInLookupView>
</column>
<column columnName="productNumber">
<shownInLookupView>true</shownInLookupView>
</column>
</columns>
</table>
</tables>
Users in the Biologics LIMS interface will now see additional detail to help them match the raw material they are using.
Use the Recipe API to Update Batches
Batches can be updated after they are created by using the Recipe API. You
can make these updates using PUT requests to recipe-batch.api:
- Mutation of materials and their associated metadata.
- Mutation of amount, amountUnits, and actualAmount of produces.
- Comments
Batches
cannot be updated in the following ways:
- Changing which sample is produced.
- Changing the source recipe (mixture).
- Changing the batch steps. Use the pre-existing recipe-notes.api endpoint if you're looking to edit these.
Use the dryRun boolean flag for pre-validation of changes without actually updating the recipe. Calling the endpoints with dryRun when experimenting/investigating will go through all the steps of validating the updates and updating the batch but it will not commit these changes. It returns what the updated batch would look like if committed.
The general steps for using the Recipe API for Batches are:
- Call recipe-getBatch.api and receive the full mixture batch definition.
- Mutate the received object in the way you'd like (change materials, amounts, etc.).
- Remove things you do not want to mutate (e.g. "produces", etc.) or similarly copy to a new object only the properties you want to mutate.
- Call recipe-batch.api and PUT the mutated object on the payload as the batch.
Related Topics
