In the LabKey Biologics data model, "Ingredients" are definitions, "Raw Materials" are physical things.
- Ingredients are virtual entities that describe the properties of a substance. For example, the Ingredient "Sodium Chloride" includes its molecular weight, melting and boiling points, general description, etc. You register an Ingredient like this only once.
- Raw Materials are physical instances of an Ingredient, tangible things that have a location in storage, with specified amounts, sources, lot numbers, locations, vessels, etc.
There is a similar relationship between Mixtures
- Mixtures are definitions. Recipe definitions, instructions for combining Ingredients.
- Batches are physical things, what you get when you combine Raw Materials according to some Mixture recipe.
This topic describes viewing registered media and steps for registration of ingredients and materials. Learn about creating mixtures and batches in these topics: Registering Mixtures (Recipes)
and Registering Batches
from the main menu to view the dashboard and manage:
brings you to a grid of available (previously created) ingredients. Click Template
to obtain an Excel template with the expected columns. Use the Add >
menu to create new ingredients:
Add a New Ingredient using a Wizard
Selecting Add > Add Manually
opens the wizard for creating a single new ingredient. This wizard is controlled by the fields in the 'Ingredients' DataClass, which can be customized by an administrator to include the fields you need. Use Edit Ingredient Design
from the Manage
menu. For example, the insert panel for ingredients might look like this:
Once required fields are completed, click Finish
and you will see the grid filtered to show only your new ingredient. Click the 'X' on the filter to return to viewing all ingredients.
Learn about using other Add
Work with Ingredients
Other actions from the grid of all ingredients are:
- Edit: Select one or more ingredient rows, then choose whether to:
- Edit in Grid
- Edit in Bulk
- Delete: Note that ingredients cannot be deleted if they have derived sample or batch dependencies, or are referenced in notebooks.
- Create Samples:
- Select one or more parent ingredients, click Create Samples, then choose which type of sample to create.
- Find Derivatives in Sample Finder: Select one or more ingredients and choose this report option to open the Sample Finder filtered to show samples with the selected ingredient components. From there you can further refine the set of samples.
Click the name of an ingredient to see the details page. On the overview you can see values set for properties of the ingredient, and if any ELNs reference this ingredient, you will see links to them under Notebooks
Using the Create
menu, you can add new Mixtures or Raw Materials with this Ingredient as a parent.
The raw materials used in mixtures are listed on the Raw Materials
Add Raw Materials in Grid
- For Raw Materials, you can select Add > Add Manually to add one or more with a grid option, as shown here.
- For Ingredients, reach a similar grid entry option by selecting Add > Add Manually from Grid.
Learn about using this grid entry interface in the Sample Manager documentation
.Add > Import from File
to add many at once from a spreadsheet, is described below
Amounts and Units
The amount of a Raw Material, and units for that amount, can be provided in two separate fields during creation.
If you have existing data prior to the addition of these two default fields in version 23.4, the text value in the previous "Amount" field for Raw Materials will be parsed into a numeric Amount field (exp.materials.storedAmount) and a text Units field (exp.materials.Units, which is a controlled set of values). We retain the text field in the RawMaterials domain, but relabel it as "AmountAndUnits". Beyond the original parsing to populate the Amount and Units, there is no ongoing connection between these fields. The AmountAndUnits field can be dropped or the individual Amount and Units fields can be hidden.
Aliquot Raw Materials
As for samples, you can create aliquots of Raw Materials, or use certain Raw Materials to create derived samples or pooled outputs. Select the desired parent material(s) and choose Derive > Aliquot Selected
or Derive or Pool as desired. Learn about sample derivation, aliquoting, and pooling here: Biologics: Create Samples
In the popup, as for creating sample aliquots
, enter the number to create (per selection), then click Go to Raw Material Creation Grid
. Aliquots of will be shown in the same grid as the original material(s). Include the IsAliquot
column in your grid view if you want to be able to filter for aliquots.
Edit Raw Materials Design
The design of this media type can be edited by selecting > Edit Raw Material Design
from the Raw Materials page. Enabling/disabling the default system fields, adding custom fields, changing field labelling, and rearranging the order can help users provide the right information when adding materials.
Learn more about editing the Raw Materials design in this topic: Sample Type Designs
When users are selecting raw materials from a dropdown, you can use lookup views to customize what details they will see
Import Ingredients and Raw Materials from File
To upload ingredients and raw materials in bulk, select Add > Import from File
A variety of file formats are supported, including Excel and TSV files. Click Template
to download a blank file with the appropriate column headings for import.
Media entities of any type cannot be deleted if they are referenced in an Electronic Lab Notebook
. On the details page for the entity, you will see a list of notebooks referencing it.
Of the 4 media types, only Ingredients
may be deleted using the Biologics interface. To delete other media entities, you must switch to the LabKey Server interface and find the relevant table.