Sample Manager Resources

LabKey Sample Manager is a sample management application designed to be easy-to-use while providing powerful lab sample tracking and workflow features.

• Overview
• Sample Manager Documentation
• Sample Manager Release Notes
• Webinar

Using Sample Manager with LabKey Server

Premium Editions of LabKey Server include the option to use the Sample Manager application within a project and integrate with LabKey Studies and other resources.

• Use Sample Manager with LabKey Server
• Use Sample Manager with Studies

Using Electronic Lab Notebooks (ELN) in Sample Manager

The Professional Edition of LabKey Sample Manager includes a user-friendly ELN (Electronic Lab Notebook) designed to help scientists efficiently document their experiments and collaborate. This data-connected ELN is seamlessly integrated with other laboratory data in the application, including lab samples, assay data and other registered data.

Learn more in this section:

• Electronic Lab Notebooks (ELN)

Premium Editions of LabKey Server include the option to use the Sample Manager application within a project and integrate with LabKey Studies and other resources.

This topic covers considerations for using Sample Manager with LabKey Server.

• Sample Manager in a Project
• Using Sample Manager in a Folder
• Export and Import of Sample Manager
• Sample Manager User Interface
• Grid Charts are Available
• Conditional Formatting is not Available
• Shared Sample Types and Source Types
• Sample Management Users and Permissions
• Use Naming Prefixes
• Configure Storage Location Options
• Storage Management API

Sample Manager in a Project

Sample Manager is designed to be contained in a project on LabKey Server. This provides advantages in scoping permissions specific to sample management. For instance, many studies in other projects may need to be linked to sample data, but a single group doing the actual sample administration and storage management for all studies would have elevated permissions on the Sample Manager folder instead of needing them on all studies.

Resources including Sample Types and Assay Designs that should be usable in both the Sample Manager project and other containers on the server should be placed in the Shared project.

• Create a new project, selecting the folder type Sample Manager.
• Configure permissions now, or leave it visible to only your own user account until you have set things up, then open permissions to your users.

Using Sample Manager in a Folder

Sample Manager is designed to be rooted at the top-level project level of LabKey Server. In some limited use cases, it may work to use Sample Manager in a subfolder, however not all features are supported. If you do not expect to share any Sample Types, Assays, or other data with other containers, and will only use a single set of container-based permissions, using Sample Manager in a subfolder may support integration with LabKey Server features and reports. Note that you cannot use Sample Manager Folders unless it is rooted at the project level.

If you choose either of the following subfolder options, you will be able to use the product selection menu to switch between Sample Manager and the traditional LabKey Server interface.

Folder of "Sample Manager" Type

You can create a new folder and select the "Sample Manager" folder type. The application will launch every time you navigate to this folder, as if it were at the project level.

Enable "SampleManagement" Module

If you want to use Sample Manager resources in a folder, but do not want to auto-navigate to the application, you can create a folder of another type (such as Study) and then enable the "SampleManagement" module via > Folder > Management > Folder Type.

You will not be navigated directly to the application in this folder, but can still reach it by editing the URL to replace "project-begin.view?" with "sampleManager-app.view?".

Export and Import of Sample Manager

Sample Manager projects and folders do not support full fidelity migration to other containers using folder export and reimport available in the LabKey Server interface. Some of the contents of Sample Manager can be migrated in this way, in some cases requiring manually migrating some data in a specific order. Others, including but not limited to Workflow and Notebook contents, cannot be moved in this way.

If you need to migrate any Sample Manager data or structures between containers, please work with your Account Manager to identify whether this is feasible in your scenario. Note that it is never possible to "promote" a folder to the project level within LabKey Server.

Sample Manager User Interface

When using Sample Manager with a Premium Edition of LabKey Server, you may see different features and options when viewing the "same" data in the two different interfaces. A few examples of differences are listed here, but this is not a comprehensive list.

Learn about switching between the interfaces in this topic:

• productSelect

Grid Charts are Available

When using Sample Manager with a Premium Edition of LabKey Server, you can define and use chart visualizations within the application. Learn more about charts in this topic for Biologics LIMS:

• LIMS: Charts

Conditional Formatting is not Available

Conditional formatting of values is not supported in Sample Manager, though you will see the controls for adding such formats in the field editor.

In order to use conditional formatting, you will need to define the formats and view your data in the LabKey Server Interface.

Shared Sample Types and Source Types

Any Sample Types and Sources defined in the /Shared project will also be available for use in LabKey Sample Manager. You will see them listed on the menu and dashboards alongside local definitions.

From within the Sample Manager application, users editing (or deleting) a shared Sample Type or Source Type will see a banner indicating that changes could affect other folders.

Note that when you are viewing a grid of Sources, the container filter defaults to "Current". You can change the container filter using the grid customizer if you want to show all Sources in "CurrentPlusProjectAndShared" or similar.

Sample Management Users and Permission Roles

An administrator in the Sample Manager or LabKey Biologics applications can access a grid of active users using the Administration option on the user avatar menu. You'll see all the users with any access to the container in which the application is enabled.

Sample Manager and Biologics both use a subset of LabKey's role-based permissions. The "Reader", "Editor", "Editor without Delete", "Folder Administrator", and "Project Administrator" roles all map to the corresponding container-scoped roles. Learn more about those permissions in this topic: permissionLevels. In addition, "Storage Editor" and "Storage Designer" roles are added to the Sample Manager and Biologics applications and described below.

Reader, Editor, and Editor without Delete

• When a user is granted the "Reader", "Editor", or "Editor without Delete" role, either in the LabKey Server folder permissions interface or the Sample Manager > Administration > Permissions tab, they will have that role in both interfaces.
• Assigning a user to a role in either place, or revoking that role in either place will apply to both the Sample Manager and LabKey Server resources in that container.

• If Sample Manager is defined in a folder, and that folder inherits permissions from a parent container, you will not be able to change role assignments within the application.

Administrator Roles

In the stand-alone Sample Manager or application, a single "Administrator" role is provided that maps to the site role "Application Admin". This also means that any "Application Admin" on the site will appear in Sample Manager as an Administrator. The Sample Manager Documentation means these site-level roles when it identifies tasks available to an "Administrator".

When using Sample Manager within LabKey Server, administrator permissions work differently. Users with the "Folder Administrator" or "Project Administrator" role on the project or folder containing Sample Manager have those roles carry into the application. These roles may also be assigned from within the application (by users with sufficient permission). The difference between these two roles in Sample Manager is that a Project Administrator can add new user accounts, but a Folder Administrator cannot. Both admin roles can assign the various roles to existing users and perform other administrative tasks, with some exceptions listed below.

As in any LabKey Server Installation, "Site Admin" and "Application Admin" roles are assigned at the site level and grant administrative permission to Sample Manager, but are not shown in the Administrator listing of the application.

Most actions are available to any administrator role in Sample Manager with some exceptions including:

• Only "Site Admin" and "Application Admin" users can manage sample statuses.

Specific Roles for Storage Management

Two roles specific to managing storage of physical samples let Sample Manager and LabKey Biologics administrators independently grant users control over the physical storage details for samples.

• Storage Editor: confers the ability to read, add, edit, and delete data related to items in storage, picklists, and jobs.
• Storage Designer: confers the ability to read, add, edit, and delete data related to storage locations and storage units.

Learn more in this topic: freezerRoles

Workflow Editor Role

The Workflow Editor role lets a user create and edit sample picklists as well as workflow jobs and tasks, though not workflow templates. Workflow editors also require the "Reader" role or higher in order to accomplish these tasks.

Administrators can also perform the tasks available to users with the Workflow Editor role.

Use Naming Prefixes

You can apply a container-specific naming prefix that will be added to naming patterns for all Sample Types and Source Types to assist integration of data from multiple locations while maintaining a clear association with the original source of that data.

When you have more than one Sample Manager project or folder, or are using both Sample Manager and LabKey Biologics on the same LabKey Server, it can be helpful to assign unique prefixes to each container.

Learn more about using prefixes here:

• Sample Manager: Apply Naming Prefix
• Biologics: Apply Naming Prefix

Configure Storage Location Options

Freezers and other storage systems can be assigned physical locations to make it easier for users to find them in a larger institution or campus. Learn more about defining and using storage locations in this topic:

• Manage Storage Locations

Storage Management API

In situations where you have a large number of storage systems to define, it may be more convenient to define them programmatically instead of using the UI. Learn more in the API documentation:

• Java Storage API
• JavaScript Storage API
• Python Storage API
• Rlabkey Package API: See labkey.storage.create/delete/update.

Related Topics

• Sample Manager Help and Documentation
• Use Sample Manager with Studies
• importExportFolder
• productSelect
• permissionLevels
• freezerRoles

Sample information can be connected to related information in a LabKey Study integrating demographic or clinical data about the study subjects from whom the samples were taken, and helping study administrators track locations of samples for those subjects.

• Include Participant and Visit Information in Sample Types
• Link Samples to Study from Sample Manager

Include Participant and Visit Information in Sample Types

Fields of specific types can be included in a Sample Type, providing participant (Subject/Participant type) and visit information (either VisitDate or VisitID/VisitLabel depending on the timepoint type of the target study). These fields can be defined either:

• On the type of the samples you want to link
• On the type of a parent sample of the samples you want to link.

Learn more in this topic: linkSampleData

Link Samples to Studies from Sample Manager

When the Sample Manager application is used on a Premium Edition of LabKey Server, you gain the ability to link samples to studies directly from within the application.

From a Samples grid, select the samples of interest using the checkboxes, then select Edit > Link to LabKey Study.

You will see the same interface for linking as when this action is initiated from within LabKey Server. To avoid errors:

• You must have the necessary alignment fields defined.
• The name of your Sample Type cannot be the same as the name of any table or dataset in the study you are linking to.

When you are viewing the linked dataset in the study, clicking View Source Sample Type will return you to the Sample Manager application UI, where you will see a column for Linked to [Study Name] populated for the linked samples.

Within Sample Manager, you can also edit your Sample Type to set the Auto-Link Data to Study option to the target study of your choice in order to automatically link newly imported samples to a given study.

Related Topics

• Use Sample Manager with LabKey Server
• linkSampleData

Use integrated and data-aware Electronic Lab Notebooks for documenting your experiments in LabKey LIMS, Biologics LIMS, and the Professional Edition of Sample Manager. These Electronic Lab Notebooks have direct access to the data you are storing and are a secure way to protect intellectual property as you develop biotherapies or perform other scientific research.

Select Notebooks from the main menu or click Notebooks Home on the home page of the application.

Learn more in the Sample Manager documentation here:

• Electronic Lab Notebooks (ELN)

Related Topics

• Manage Notebook Tags (Available in Biologics LIMS only)
• ELN: Frequently Asked Questions

Within LabKey Biologics LIMS and the Professional Edition of LabKey Sample Manager, you can use data-integrated Notebooks for documenting your experiments. These electronic lab notebooks are directly integrated with the data you are storing and are a secure way to protect intellectual property as you work.

How can I use Notebooks for my work?

Notebooks are available in the Biologics and Sample Manager applications.

• Already using Biologics? You'll already have Notebooks, provided you are on a current version.
• Already using Sample Manager? You'll need to be using the Professional Edition of Sample Manager, or the Enterprise Edition of LabKey Server to access Notebooks.
• Not using either of the above? Please contact us to learn more.

Who can see my Notebooks?

Every user with "Read" access to your folder can also see Notebooks created there.

What can I reference from a Notebook?

You can reference anything in your application, including data, experiments, specific samples, and other notebooks. Use a direct reference selector to place a color coded reference directly in your Notebook text. Add a single reference at a time, or add multiple references in bulk.

The combined list of all elements referenced from a notebook is maintained in an Overview panel.

Learn more in this topic: Add a Reference

How are Notebooks locked and protected once signed?

After the notebook has been approved we create a signed snapshot. The snapshot will include all notebook data including:

• Notebook metadata and text
• Any data referenced in the notebook (samples, entities, experiments, assay runs, etc.)
• Attached files

What happens to my Notebooks when I upgrade?

• Once you create a Notebook, it will be preserved (and unaltered) by upgrades of LabKey.

What are team templates?

"Team templates" is a term that was in use in earlier versions for templates that are now called Shared Templates.

When you view the Notebook Templates Dashboard, all the templates you created are listed on the Your Templates tab. Templates created by yourself or other users and shared (i.e. team templates) are listed on the Shared Templates tab.

Related Topics

• Electronic Lab Notebooks

LabKey LIMS is easy to use laboratory information management system software that will optimize your laboratory workflows for maximum productivity and empower data-driven decision making with our visualization and reporting tools.

LabKey LIMS includes all features available in the Professional Edition of Sample Manager, plus:

• Generate customizable reports with ease.
• Add automation with transformation scripts for assay data.
• Customize the downloadable templates for data structures like samples, sources, and assays.

• LabKey LIMS Release Notes

Data structures including Samples, Sources, and Assay Designs offer users a downloadable template to make it easier to structure data correctly for import. The default template includes all fields in the data structure. Administrators of LabKey LIMS can provide users with a selection of custom templates to suit different import scenarios.

• Add Custom Templates (Administrator)
• Download Templates

Add Custom Templates (Administrator)

• Open the Sample Type, Source Type, or Assay Design for which you want to include customized templates.
• Select Manage > Manage Templates.

• You'll see the Default Template and can click to download it as a starting place if desired.
• Click Add a Template to add your own additional ones.

• Give the new template a name that will help your users know when to use it.
• Select or drag and drop the new template file into the target area.
• Click Save.

Download Templates

When a data structure has more than the default template defined, users will be able to select a template by name.

Related Topics

• Use Import Templates

LabKey LIMS and Biologics LIMS represent a variety of materials in various phases of bioprocessing using Samples. Samples of many different types can be defined to represent your laboratory processes. They can be standalone compounds, they can have parentage/lineage, they can be aliquoted, used to derive new samples, or pooled.

Sample Types define the fields and properties for the different kinds of samples in your system. Learn more about creating Sample Types and adding and managing Samples in the Sample Manager documentation:

• Sample Types:
• Sample Types Dashboard
• Create Sample Types
• Sample Type Details and Insights
• Sample Grid Menus
• Samples:
• Add Samples
• Aliquots, Derivatives, and Sample Pooling
• Sample Details: Lineage, Aliquots, Assays, Jobs, Timeline
• Sample Status
• Sample Picklists
• Sample Grids Containing Samples of Several Types
• Multi-tab Excel Exports
• Sample Finder

Related Topics

• Entity Lineage
• sampleSets: General information about Sample Types
• sampleIDs
• labkeyDataStructures
• useSampleSets
• deriveSamples
• exampleSampleSets
• uniqueStorageIds
• dataClass
• barTender

Assay data is captured in LabKey LIMS using Assay Designs. Each Assay Design includes fields for capturing experimental results and metadata about them. Each field has a name and data type, for example, the following Assay Design represents data from a Titration experiment.

An administrator configures the Assay Designs necessary for the organization, then users can import and work with the data that conforms to those formats. Topics are divided by role, though both users and admins will benefit from understanding how assay designs work and how they are used.

Documentation

Learn more about using the general assay framework in the Sample Manager documentation here:

• Experiment and Assay Data
• Describe Assay Data Structure
• Import Assay Data
• Manage Assay Designs
• Manage Assay Data

Additional Features with LabKey LIMS

• LIMS: Charts

Additional Features with Biologics LIMS

• Use Specialty Assays
• Include File Field Data with Assay Results
• Integrate Assay Data with Bioregistry Entities
• Assay Batch Fields
• Use Assay QC States

When administrators add charts or other visualizations in LabKey Server, they are surfaced above the corresponding data grid in the LabKey LIMS and Biologics applications.

• Add a Chart
• View a Chart
• Edit a Chart
• Error Bars
• Export a Chart as PNG or PDF

Add a Chart

To add a chart:

• On a data grid, click the Charts menu and choose Create Chart.

• In the pop up dialog, enter the following fields and options:
• Enter a Name and select whether to:
• Make this chart available to all users
• Make this chart available in child folders
• Select a Chart Type:
• Bar
• Box
• Line
• Pie
• Scatter
• Depending on the chart type, you will see selectors for X-axis, Y-axis, and various other settings needed for the chart. Required fields are marked with an asterisk.
• Once you have made selections, you will see a preview of the chart.

• Click Create Chart to save it.

Trendline Options

• Trendline Options for Line Plots

View a Chart

Any charts available on a data grid will be listed on the Charts menu above the grid.

Selecting a chart will render it above the grid as shown here.

Select up to 5 charts for display.

Edit a Chart

To edit a chart, open it from the menu and click the .

You'll see the same interface as when you created it and be able to make any adjustments. Click Save Chart when finished.

You can also click to Delete Chart from the edit panel.

Error Bars and Aggregation Methods

For Bar and Line charts, aggregation and error bar options are available by clicking the Y-axis gear icon.

When the aggregation method is set to Mean, then the options for error bars are shown: None, Standard Deviation, Standard Error of the Mean.

Export a Chart as PDF or PNG

Click the (Download) button to choose either PNG or PDF format for your export.

Related Topics

• Biologics: Detail Pages and Entry Forms
• reportsAndViews

Managing the contents of your freezers and other storage is an essential component of sample management in a biologics research lab. There are endless ways to organize your sample materials, in a wide variety of storage systems on the market. With LabKey Freezer Management, create an exact virtual match of your physical storage system and track the samples within it.

Topics

Learn more in the Sample Manager documentation here:

• Storage Management
• Create Storage
• Store Samples
• Manage Storage
• Manage Storage Unit Types
• View Storage Details
• Edit Storage Definition
• Manage Storage Locations
• Move Stored Samples
• Manage Stored Samples
• Check Out and Check In
• View Storage Activity
• Migrate Storage Data into LabKey
• freezerRoles
• Storage Management API
• Shared Storage Across Folders

Workflow tools make it easy to plan and track your tasks:

• Use workflow templates to standardize common task sequences
• Create jobs to track and prioritize sequential tasks
• Assign work to the right users
• Track progress toward completion

Creating and managing jobs, templates, and task queues is documented in the Sample Manager Help topics here:

• Sample Manager Workflow

LabKey Biologics LIMS is designed to enable biopharma and bioprocessing research teams to manage and interlink samples, data, entities, workflows, and electronic laboratory notebooks. New features of Biologics LIMS will improve the speed and efficiency of antibody discovery operations for emerging biotechs.

This "data-connected" solution goes beyond traditional LIMS software supporting the specific needs of molecular biologists, protein scientists, analytical chemists, data scientists and other scientific disciplines.

• Record and document your ongoing work in a data-aware Electronic Lab Notebook.
• Easily and uniquely register all biological entities individually or in bulk.
• Track and query the lineage of samples throughout many generations of derivation.
• Integrate biological entity and sample information with downstream assay data used to evaluate therapeutic properties and provide a holistic view of experiment results.
• Manage and monitor the execution of laboratory tasks and requests, supporting efficient collaboration across teams.
• Manage the contents of your freezers and other storage systems using a digital match for your physical storage.

• LabKey Biologics LIMS

Biologics Release Notes

• Release Notes: Biologics LIMS

Biologics Overview

• Introduction to LabKey Biologics

• Sample Manager Help
• Get Started with Sample Manager

Basic Navigation and Features

• Navigate the Dashboard and Menus
• Search
• Biologics: Terminology
• Biologics: Projects and Folders

Bioregistry

• Biologics: Bioregistry
• Create Registry Sources
• Register Nucleotide Sequences
• Register Protein Sequences
• Register Leaders, Linkers, and Tags
• Register Molecules
• Protein Sequence Annotations
• CoreAb Sequence Classification
• Biologics: Chain and Structure Formats
• Molecules, Sets, and Molecular Species
• Vectors, Constructs, Cell Lines, and Expression Systems
• Entity Lineage
• Bulk Registration of Entities
• Registry API
• Configuring Columns Seen in Grids and Detail Views
• Biologics: Protect Sequence Fields

Samples

• Sample Manager Documentation

Plates

• Biologics: Plates

Assay Management

• Biologics: Assay Data
• Biologics: Assay Batches and QC
• Biologics: Upload Assay Data
• Biologics: Specialty Assays

Media Registration

• Biologics: Media Registration
• Managing Ingredients and Raw Materials
• Registering Mixtures (Recipes)
• Registering Batches

Workflow

• Workflow Management

ELN

• Electronic Lab Notebook

Storage Management

• Storage in Sample Manager

Related Topics

• User Accounts and Avatars
• Domain Templates

• LabKey Biologics: Home Page
• Header Menus
• Navigation
• Menu > Registry Sources - Browse all of the registry sources.
• Menu > Sample Types - A dashboard for tracking samples.
• Menu > Assays - Assay results for candidate molecules.
• Menu > Storage - Manage freezer contents and capacities.
• Menu > Workflow - Create and track custom workflow jobs and tasks.
• Menu > Media - A dashboard for ingredients, media, mixtures, and recipes. (Enterprise Edition Feature)
• Menu > Picklists - User-defined lists of samples.
• Menu > Notebooks - Electronic lab notebooks integrated directly with your data.

LabKey Biologics: Home Page

The main dashboard on the home page provides quick links into different aspects of the data.

The top header bar is available throughout the application and includes:

• The clickable logo, for returning to this dashboard at any time.
• A main Menu button, giving access to all of your data and activities.
• A set of common resources in the upper right:
• : Search options
• : A product selection menu for switching between Biologics and LabKey Server when needed
• : Notifications
• : Help Opens the documentation for LabKey Biologics LIMS.
• : Administration Settings
• A user menu, indicated by your avatar, or a default graphical one

On the dashboard, you'll see panels displaying:

• Dashboard Insights: A selectable set of visualizations, defaulting to the Sample Count by Status.
• Sample Types can be selectively excluded from the graphs on this dashboard, as described here.
• Notebooks: See task status, recent notebooks, and link to your Electronic Lab Notebooks dashboard.
• Locations Recently Added To: Access to storage where samples have been added by you or others.
• Jobs List: The home for workflow jobs. If any tasks were assigned to you, they would be shown on Your Job Queue and can be filtered by priority.

Header Menus

The menus in the upper right offer these selections:

• : Search options:
• Site-wide text search
• Find samples by barcode () or ID ()
• Sample Finder: Find samples by their properties or associated data
• : A product selection menu for switching between Biologics and LabKey Server when needed
• : Notifications
• Documentation:
• Help: Opens the documentation for LabKey Biologics LIMS.
• Release Notes: Biologics

• : Administration Settings:
• Application Settings: See below.
• Audit Logs
• Groups
• Permissions
• Folders
• Users
• User avatar menu
• Notification Settings
• Profile: Your user details, including the option to add an avatar image.
• Sign Out (or Sign In)

Application Settings

Select > Application Settings to manage:

• Display Settings
• Notebook Settings
• BarTender Configuration
• ID/Name Settings
• Manage Sample Statuses
• Audit Logging
• Protected Data Settings

Navigation

The main Menu is available throughout the application and gives you quick access to all aspects of Biologics. It will include the name of the category you are in ("Dashboard" if not one of the specific categories).

Click the menu categories for sub-dashboards, such as for Registry Sources, Notebooks, or Sample Types. Click individual menu items for that specific category.

• Biologics: Bioregistry
• samples
• Biologics: Assay Data
• LIMS: Storage Management
• LIMS: Workflow
• Biologics: Media Registration
• Electronic Lab Notebooks

The LabKey Biologics application supports collaboration among multiple teams or projects by using LabKey containers (folders) to hold and selectively share data. This topic covers considerations for designing your system.

• Options for Sharing Biologics Data
• Use Multiple Biologics Folders
• Cross-Folder Actions
• Restricted Visibility of Inaccessible Data
• ID/Name Settings
• Force Usage of Naming Patterns for Consistency
• Apply Naming Prefix
• Naming Pattern Elements/Tokens
• Shared Data Structures (Sample Types Registry Source Types, Assays, Storage Systems)

Options for Sharing Biologics Data

Biologics runs in the context of a LabKey project or folder container. Each container can have unique permissions assignments and data, supporting a secure and isolated workspace. If desired, many resources, including assay designs and sample type definitions, can also be shared across multiple containers. Further, within a LabKey project of type "Biologics", an administrator can add folders which allow data partitioning.

The Biologics administrator should determine the configuration that best represents the organization.

Example Scenarios:

1. You might have two groups doing distinct work with no need to share data or compare results. These two groups could each use a separate Biologics container (LabKey project or folder) and keep all resources within it. Permissions are assigned uniquely within each container, with no built-in interaction between the data in each.

2. If two groups needed to use the same assay designs or sample types, but would not otherwise share or compare the actual data, those definitions could be placed in the Shared project, with all collection and analysis in containers (LabKey projects or folders) for the two groups as in option 1. Note that in this scenario, samples created of those shared types would have the same naming pattern and if you used a container-specific prefix, it would not be applied to the samples of the shared type.

3. If multiple groups need to share and compare data, and also keep clear which data came from which group originally, you could apply a container prefix in each group's folder so that all data would be consistently identified. In this scenario, each container would need its own sample type definitions so that the naming patterns would propagate the prefix into the created samples.

4. For more integrated sharing, configure Biologics in a top level LabKey project, then add one or more subfolders, all also of folder type "Biologics". Bioregistry and Sample definitions can be shared among the Folders and permissions controlled independently. Learn about this option in the next section.

5. Storage systems (freezers, etc.) can be shared among folders with different permissions. Users will only be able to see details for the stored samples to which they have been granted access. Learn more about shared storage in the Sample Manager documentation:

• Share Storage Across Folders

Manage Multiple Biologics Folders

When using Biologics in a top-level LabKey Server container, administrators have the option to manage multiple Biologics Folders directly from within the admin interface. Note that this is not supported when the top level Biologics container is a folder or subfolder in LabKey Server.

To manage Folders, select > Folders. You can customize types of data and specific storage systems available per Folder. Learn more in the Sample Manager documentation here:

• Folder Organization

Cross-Folder Actions

When multiple Biologics Folders are in use, the notes about cross-folder actions are the same as for Sample Manager, where Registry Sources are called Sources. Learn more in this topic:

• Cross-Folder Actions

Restricted Visibility of Inaccessible Data

When a user has access to a subset of folders, there can be situations where this user will be restricted from seeing data from other folders, including identifiers such as Sample IDs that might contain restricted details. In detail pages, listing pages, and grids, entities a user does not have access to will show "unavailable" in the display instead of a name or rowid. Learn more in this topic:

• Restricted Visibility of Inaccessible Data

ID/Name Settings

Select > Application Settings and scroll down to the ID/Name Settings section to control several options related to naming of entities in the application.

Force Usage of Naming Patterns for Consistency

To maintain consistent naming, particularly when using container-specific naming prefixes, you may want to restrict users from entering their own names for entities. Learn more here:

• Allow/Disallow User-defined IDs/Names

Apply Naming Prefix

You can apply a container-specific naming prefix that will be added to naming patterns to assist integration of data from multiple locations while maintaining a clear association with the original source of that data.

This prefix is typically short, 2-3 characters long, but will not be limited. Prefixes must be unique site-wide, and should be recognizable to your users. Before setting one, make sure you understand what will happen to the naming patterns and names of existing entities in your application.

• The prefix will be applied to names created with naming patterns for all Sample Types and Registry Source Types in the container.
• New samples and entities created after the addition of the prefix will have names that include the prefix.
• Existing samples and entities created prior to the addition of the prefix will not be renamed and thus will not have the prefix (or might have a different previously-applied prefix).
• Sample aliquots are typically created and named including the name of the sample they are aliquoted from. This could mean that after the prefix is applied, new aliquots may or may not include the prefix, depending on whether the originating sample was created before or after the prefix was applied. Learn more about aliquot naming here: aliquotIDs.

To set a container prefix:

• Select > Application Settings.
• Scroll down to the ID/Name Settings section.
• Enter the prefix to use. You will see a preview of what a name generated with the Naming Pattern with the prefix applied might look like using a representative example, Blood-${GenId}:

• Click Apply Prefix to apply it.
• This action will change the Naming Pattern for all new and existing Sample Types and Registry Source Types. No existing IDs/Names will be affected. Are you sure you want to apply the prefix?
• Click Yes, Save and Apply Prefix to continue.

Naming Pattern Elements/Tokens

The sampleCount and rootSampleCount tokens are used in Naming Patterns across the application.

Learn more about these naming pattern tokens in this topic:

• Incrementing Sample Counters

Shared Data Structures (Sample Types, Registry Source Types, Assays, and Storage)

Sample Types, Registry Source Types, Assays, and Storage Systems are defined in the home folder and available in subfolders, provided an administrator has not 'hidden' them. Administrators can edit these shared data structures from the home any folder, but the changes will be made at the home level, applying to all folders.

In addition, any Sample Types, Registry Source Types, and Assay definitions defined in the /Shared project will be available for use in LabKey Biologics. You will see them listed on the menu and dashboards alongside local definitions.

From within the Biologics application, users editing (or deleting) a shared definition will see a banner indicating that changes will affect other folders. The same message is applied when editing a data structure from a folder within the Biologics application.

Note that when you are viewing a grid for any Registry Source Type, the container filter defaults to "Current". You can change the container filter using the grid customizer if you want to show all Registry Sources in "CurrentPlusProjectAndShared" or similar.

Related Topics

• sampleIDs
• aliquotIDs
• Cross-Folder Actions

The following topics explain how to use the LabKey Biologics Bioregistry, including how to register new entities and navigate the existing data.

The Registry Sources in Biologics LIMS are structured in the same way and behave as do Sources in the Sample Manager application. Many topics in this section refer to the Sample Manager documentation for Sources for general usage details.

• Create Registry Sources
• Register Nucleotide Sequences
• Register Protein Sequences
• Register Leaders, Linkers, and Tags
• Register Molecules
• Registry Reclassification
• Biologics: Terminology
• Protein Sequence Annotations
• CoreAb Sequence Classification
• Biologics: Chain and Structure Formats
• Molecules, Sets, and Molecular Species
• Vectors, Constructs, Cell Lines, and Expression Systems
• Compounds and SMILES Lookups
• Entity Lineage
• Customize the Bioregistry
• Bulk Registration of Entities
• Use the Registry API
• Biologics: Detail Pages and Entry Forms

This topic describes how to use the Biologics application to create new Registry Sources, i.e. members of any Registry Source Type, including cell lines, molecules, nucleotide sequences, expression systems, etc. Users creating these entities may specify a name, or have one generated for them using a naming pattern. Names can also be edited later. If desired, administrators may also hide the ability to specify or edit names.

• Create Registry Sources in the User Interface
• Create/Import Registry Sources from File
• Obtain Template
• Update or Merge Registry Sources from File
• Naming Patterns
• Hide Name Entry/Edit Options
• Review Entity Details

Create Registry Sources in the User Interface

In this example, we show creation of a new cell line. Other kinds of sources will have different fields that compose them, and may also have additional tabs in the creation wizard. See specific documentation listed at the end of this topic.

• From the main menu, click the type of registry source to create. Then use the Add > menu:
• Add Manually: Use the data entry wizard.
• Add Manually from Grid: Create one or more using a grid interface.
• Import from File

Add Manually

• Provide the details in the registration wizard:

• Name: Provide a short unique name, or leave this field blank to have one generated using the naming pattern for this Registry Source Type.
• Hover over the to see an example generated name.
• Description: Optional, but will be shown in the grids and can be a helpful way to illustrate the entity.
• Common Name: Every entity includes a field for the common name.
• Remaining fields: Required fields are marked with an asterisk.
• When the fields are completed, click Finish to create the new entity.

You can now return to the grid for this Registry Source Type (i.e. Cell Lines in this example) to find your new entity later.

Add Manually from Grid

Using the grid interface to create Registry Sources as described in the Sample Manager documentation for Sources.

Note that this option not supported for all Registry Source Types. You will not see this option on the menu for Nucleotide Sequences, Protein Sequences, Molecules, Molecular Species, etc.

Create/Import Entities from File

For bulk registration of many entities, including registry sources, samples, assay result data, ingredients, and raw materials, you can make use of importing new data from file. Templates are available to assist you in reliably uploading your data in the expected format.

Learn more in the Sample Manager documentation for importing Samples from file.

Update or Merge Registry Sources from File

To update data for existing Registry Sources from file, or to import a spreadsheet merging updates with creation of new Registry Sources, use Edit > Update from File.

Learn more in the Sample Manager documentation for updating Samples from file.

Entity Naming Patterns

If you do not provide a name, the naming pattern for the Registry Source Type will be used to generate one. Hover over the to see the naming pattern in a tooltip, as well as an 'example name' using that pattern.

The default naming patterns in LabKey Biologics are:

To change a naming pattern, edit the Registry Source Type design and provide a different one.

Hide Name Entry/Edit Options

An administrator can hide the Name field for insert, update, or both. When insert of names is hidden, they will be generated using the naming pattern for the registry source type. When update of names is hidden, names remain static after entity creation.

This can be done:

• On an application-wide basis by disabling user-supplied names entirely.
• For some but not all Registry Source Types, by using Query Metadata overrides.

Review Registry Source Details

Once created, you'll see a grid of all entities of the given type when you select it from the main menu.

To see details for a specific Registry Source, click the name.

As for Sources in Sample Manager, tabs provide more detail. Learn more in the Sample Manager documentation for Sources.

• Overview: Panels for details, samples, related entities (for built in Registry Source Types), notebooks, and parent sources.
• Lineage: See the lineage in graph or grid format.
• Samples: Contains a grid of all samples 'descended' from this source.
• Assays: See all assay data available for samples 'descended' from this source.
• Jobs: All jobs involving samples 'descended' from this source.

• Sequence (Available for Protein and Nucleotide Sequences).
• Molecular Property Calculator (Available for Molecules)

Related Topics

• Edit Registry Sources
• Register Nucleotide Sequences
• Register Protein Sequences
• Register Molecules
• Molecules, Sets, and Molecular Species
• Vectors, Constructs, Cell Lines, and Expression Systems

This topic covers how to register a new nucleotide sequence using the graphical user interface. To register using the API, or to bulk import sequences from an Excel spreadsheet, see Use the Registry API.

• Nucleotide Sequence Validation
• Create a Nucleotide Sequence
• Details Tab
• Confirm Tab

Nucleotide Sequence Validation

For nucleotide sequences, we allow DNA and RNA bases (ACTGU) as well as the IUPAC notation degenerate bases (WSMKRYBDHVNZ). On import, whitespace will be removed from a nucleotide sequence. If the sequence contains other letters or symbols, an error will be raised.

For protein sequences, we only allow standard amino acids letters and zero or more trailing stop codon '*'. On import, whitespace will be removed from a protein sequence. If the sequence contains stop codons in the middle of the sequence or a other letters or symbols, an error will be raised.

When translating a nucleotide codon triple to a protein sequence, where the codon contains one or more of the degenerate bases, the system attempts to find a single amino acid that could be mapped to by all of the possible nucleotide combinations for that codon. If a single amino acid is found, it will be used in the translated protein. If not, the codon will be translated as an 'X'.

For example, the nucleotide sequence 'AAW' is ambiguous since it could map to either 'AAA' or 'AAT' (representing Lysine and Asparagine respectively), so 'AAW' will be translated as an 'X' However, 'AAR' maps to either 'AAA" or 'AAG' which are both are translated to Lysine, so it will be translated as a 'K'.

Create a Nucleotide Sequence

To add a new nucleotide sequence to the registry:

• Open the Nucleotide Sequence page, then select Add > Add manually.

The creation wizard has two tabs:

• Details
• Confirm

Details

On the Register a new Nucleotide Sequence page, in the Details panel, populate the fields:

• Name: Provide a name, or one will be generated for you. Hover to see the naming pattern
• Description: (Optional) A text description of the sequence.
• Alias: (Optional) Alternative names for the sequence. Type a name, click enter when complete. Continue to add more as needed.
• Common Name: (Optional) The common name for this sequence, if any.
• Nucleotide Sequence Parents: (Optional) Parent components. A related sequence the new sequence is derived from, for example, related as a mutation. You can select more than one parent. Start typing to narrow the pulldown menu of options.
• Sequence: (Required) The nucleotide sequence
• Annotations: (Optional) A comma separated list of annotation information:
• Name - a freeform name
• Category - region or feature
• Type - for example, Leader, Variable, Tag, etc.
• Start and End Positions are 1-based offsets within the sequence.
• Description
• Complement

Confirm

Review the details on the Confirm tab.

Options to complete registration:

• Finish: Register this nucleotide sequence and exit.
• Finish and translate protein: Both register this nucleotide sequence and register the corresponding protein. This option will take you to the registry wizard for a new protein, prepopulating it with the protein sequence based on the nucleotide sequence you just defined.

Related Topics

• Register Protein Sequences
• Create Registry Sources

This topic covers how to register a new protein sequence using the graphical user interface. To register entities in bulk via file import, see Create Registry Sources. To register entities using the API, or to bulk import sequences from an Excel spreadsheet, see Use the Registry API.

• Protein Sequence Wizard
• Details
• Sequence
• Annotations
• Properties
• Confirm

• Via the nucleotide sequence wizard. When registering a nucleotide sequence, you have the option of continuing on to register the corresponding protein sequence.
• Via the header bar. Select Registry > Protein Sequences.
• Select Add > Add manually.

Protein Sequence Wizard

The wizard for registering a new protein sequence proceeds through five tabs:

Details

• Name: Provide a name, or one will be generated for you. Hover to see the naming pattern
• Description: (Optional) A text description of the sequence
• Alias: (Optional) List one or more aliases. Type a name, click enter when complete. Continue to add more as needed.
• Organisms: (Optional) Start typing the organism name to narrow the pulldown menu of options. Multiple values are accepted.
• Protein Sequence Parents: (Optional) List parent component(s) for this sequence. Start typing to narrow the pulldown menu of options.
• Seq Part: (Optional) Indicates this sequence can be used as part of a larger sequence. Accepted values are 'Leader', 'Linker', and 'Tag'. When set, chain format must be set to 'SeqPart'.

Sequence

On the sequence tab, you can translate a protein sequence from a nucleotide sequence as outlined below. If you prefer to manually enter a protein sequence from scratch click Manually add a sequence at the bottom.

• Nucleotide Sequence: (Optional) The selection made here will populate the left-hand text box with the nucleotide sequence.
• Translation Frame: (Required). The nucleotide sequence is translated into the protein sequence (which will be shown in the right-hand text box) by parsing it into groups of three. The selection of translation frame determines whether the first second or third nucleotide in the series 'heads' the first group of three. Options: 1,2,3.
• Sequence Length: This value is based on the selected nucleotide sequence.
• Nucleotide Start: This value is based on the nucleotide sequence and the translation frame.
• Nucleotide End: This value is based on the nucleotide sequence and the translation frame.
• Translated Sequence Length: This value is based on the nucleotide sequence and the translation frame.
• Protein Start: Specific the start location of the protein to be added to the registry.
• Protein End: Specific the end location of the protein to be added to the registry.

Click Next to continue.

Annotations

The annotations tab displays any matching annotations found in the annotation library. You can also add annotations manually at this point in the registration wizard.

• Name: a freeform name
• Type: for example, Leader, Variable, Tag, etc. Start typing to narrow the menu options.
• Category: 'Feature' or 'Region'
• Description: (Optional)
• Start and End Positions: 1-based offsets within the sequence

Suggested annotations can be “removed” by clicking the red icons in the grid panel. They can also be added back using the green icon if the user changes their mind.

For complete details on using the annotation panel see Protein Sequence Annotations.

Click Next to continue the wizard.

Properties

• Chain Format: select a chain format from the dropdown (start typing to filter the list of options). An administrator defines the set of options on the ChainFormats list. LabKey Biologics will attempt to classify the protein's chain format if possible.
• ε: the extinction coefficient
• Avg. Mass The average mass
• Num. S-S The number of disulfide bonds
• pI The isoelectric point
• Num Cys. The number of cysteine elements

Default or best guess values may prepopulate the wizard, but can be edited as needed.

Click Next to continue.

Confirm

The Confirm panel provides a summary of the protein about to be added to the registry.

Click Finish to add the protein to the registry.

Editing Protein Sequence Fields

Once you have defined a protein sequence, you can locate it in a grid and click the name to reopen to see the details. Some fields are eligible for editing. Those that are "in use" by the system or other entities cannot be changed. All edits are logged.

Related Topics

• Protein Sequence Annotations
• CoreAb Sequence Classification
• Register Leaders, Linkers, and Tags
• Register Nucleotide Sequences
• Create Registry Sources

In LabKey Biologics, when you register a leader, linker, or tag, the annotation system will use it in subsequent classifications of molecules. This topic describes how to register leaders, linkers, and tags.

To register:

• From the main menu, click Protein Sequences.
• Select Add > Add Manually.

• This will start the wizard Register A New Protein Sequence.

• Leader
• Linker
• Tag
• Click Next.

• On the Sequence tab, scroll down and click Manually add a sequence.

• Enter the sequence and click Next.

• Complete the rest of the wizard as described in the topic Register Protein Sequences.

Related Topics

• Register Protein Sequences

The LabKey Biologics registry can capture Vectors, Constructs, Cell Lines, Expression Systems, and their relationships. To add these entities to the registry, use the creation wizard for the desired type. Creation in bulk via file import is also available.

• Definitions
• Add Manually within the User Interface
• Add Manually from Grid
• Import from File

Definitions

• Vectors are typically plasmids that can inject genetic material into cells. Must have a specific nucleotide sequence.
• Constructs are Vectors which have been modified to include the genetic material intended for injection into the cell.
• Cell Lines are types of cells that can be grown in the lab.
• Expression Systems are cell lines that have been injected with a construct.

Add Manually within the User Interface

Select the desired entity from the main menu, then select Add > Add Manually.

The default fields for each entity type are shown below. General instructions for creating entities are in this topic: Create Registry Sources

Note that the default fields can be changed by administrators to fit your laboratory workflows, requirements, and terminology. For details about customizing them, see Biologics: Detail Pages and Entry Forms.

Add Manually from Grid

Select the desired entity from the main menu, then select Add > Add Manually from Grid. Learn about creating entities with this kind of grid in the topic:

• Create Samples from Grid

Import from File

Creation of many entities of a given type can also be done in bulk via file import using a template for assistance. Select Add > Import from File and upload the file. Learn more in this topic:

• Create Via File Import

Related Topics

• Create Registry Sources

Most stages of Biologics development, Discovery included, require proper characterization of sequences and molecules to make good project advancement decisions. Being able to adjust the classification and physical property calculation of Protein Sequences (PS) and Molecules is key to ensuring trustworthy information about those entities. This topic covers how to update annotations and characteristics that affect physical properties if they change over time or were originally entered incorrectly.

• Reclassify Protein Sequence
• Update Annotations
• Update Molecules
• View Classification Status from Molecule

Reclassify Protein Sequence

From the Protein Sequences dashboard, select the protein sequence you wish to reclassify. Select Manage > Reclassify.

Update Annotations

On the first page of the reclassification wizard, you will see the current Chain Format and Annotations for the sequence.

Reclassification actions include:

• Review any updates to the Annotations that have been introduced since this protein sequence was last classified. These will be highlighted in green as shown below this list.
• Review the Chain Format assignment that may have been recalculated since the original classification. If needed, you can select another Chain Format.
• Add additional Annotations. Complete the required elements of the Add Annotation section, then click Add.
• Delete previous annotations using the in the "Delete" column. You'll see the deleted annotation struck out and have the option to re-add it by clicking the before continuing.

Adjust Molecules

After reviewing and adjusting the annotations, click Next to continue to the Molecules reclassification step.

Select molecules to reclassify in the grid. Reclassification may change their Molecular Species and Structure Format. Molecules that use a selected molecule as a component or sub-component will also be reclassified. Unselected molecules won't be changed, and will be given a classification status of "Reclassification Available".

Click Finish to complete the reclassification.

You can return to the Protein Sequence's reclassification interface later to select and reclassify remaining molecules.

View Classification Status from Molecule

Starting from the overview page for a Molecule, you can see the Classification Status in the Details panel.

If this indicates "Reclassification Available" you can return to the relevant Protein Sequence to reclassify it. Component Protein Sequences are listed below the Molecule details to assist you.

Related Topics

• Register Protein Sequences
• Register Molecules

This topic defines some common terminology used in LabKey Biologics LIMS. It also outlines the default Registry Source Types in the Biologics application, and their relationships to one another. You can access this information within the application by selecting Registry from the main menu, then clicking See entity relationships at the top of the page.

• Definitions: "Registry Source" vs "Sample"
• Diagram of Registry Source Relationships
• Details of Each Registry Source Type

Definitions: "Registry Source" vs "Sample"

In LabKey Biologics LIMS, the terms "registry" and "samples" refer to different components or aspects of the system. The Registry is a database or collection of information about biologics entities, while Samples refer to the actual biological material or representations of it that are being managed within the system. The registry helps organize and provide context to the information about these entities, and samples are the tangible or digital representations linked to these entries in the registry.

Registry Sources:

• "Registry" typically refers to a comprehensive database or collection of information related to biologics entities. This can include details about biologics, such as antibodies, cell lines, or other biological molecules, that are being studied or managed within the system. The registry serves as a centralized repository for metadata and information about these biological entities, "Registry Sources", often including details like names, identifiers, descriptions, origin, properties, and associated data.

• "Samples" in LabKey Biologics usually refer to the physical or virtual representations of biological material that have been collected, stored, and are being managed within the system. Samples can include a variety of biological materials such as tissues, cell lines, fluids, or other substances. Each sample is typically associated with specific information, like collection date, source, location, processing history, and other relevant details. Samples are often linked to entries in the registry to provide a clear relationship between the biological entity and the actual physical or virtual sample associated with it.

Diagram of Registry Source Relationships

• A Sequence is inserted into an empty
• Vector to create a
• Construct.
• A host Cell Line and a Construct combine to form an
• Expression System, which generates
• Molecules.
• Molecules are composed of:
• Protein Sequences
• Nucleotide Sequences
• and/or other molecules.
• Molecule Sets group together molecules with the same mature sequence.
• Molecular Species are variants of molecules.

Molecule

Composed of a mixture of protein sequences, nucleotide sequences, chemistry elements, and other molecules. Generally, "molecule" refers to the target entity.

Molecule Set

The set of molecules that only differ from one another in terms of their leader sequences. See Vectors, Constructs, Cell Lines, and Expression Systems.

Molecular Species

After protein expression and other processes, all the entities that are detected for a particular molecule (different cleavage sites, post-translational modifications, genomic drift). See Vectors, Constructs, Cell Lines, and Expression Systems.

Protein Sequence

Single sequence comprised of amino acids (20 different amino acids).

Nucleotide Sequence

A single sequence comprised of nucleic acids, can be either DNA (A, T, G, C) or RNA (A, U, G, C).

Along with being a component of a molecule, DNA sequences can be designed that encode for specific protein sequences when transferred into a cell line to create an expression system.

Vector

DNA molecule used as a vehicle to artificially carry foreign genetic material into another cell. The most common type of vector is a plasmid - a long double-stranded section of DNA that has been joined at the ends to circularize it. In molecular biology, generally, these plasmids have stretches of DNA somewhere in their makeup that allow for antibiotic resistance of some sort, providing a mechanism for selecting for cells that have been successfully transfected with the vector.

Construct

A vector (generally a plasmid) that has had a stretch of DNA inserted into it. Generally, this DNA insertion encodes for a protein of interest that is to be expressed.

Cell Line

A host cell line is transfected with a Construct, bringing the new DNA into the machinery of the cell. These transfected cells (called an Expression System) are then processed to select for cells that have been successfully transfected and grown up, allowing for the production of cells that have the construct and are manufacturing the protein of interest. At times, these transfections are transient and all of the cells are used in the process. Other times, a new stable cell line (still a Cell Line) is produced that can continue to be used in the future.

Expression System

A combination of a Construct and a host cell

Related Topics

• Vectors, Constructs, Cell Lines, and Expression Systems

When a protein sequence is added to the registry, the system searches an internal library for matching annotations. Matching annotations are automatically associated with the protein sequence and displayed in a viewer. Protein annotations can also be added manually, edited, and removed for a registered sequence (protein or nucleotide).

Learn more about the methodology used in this internal library in this topic:

• CoreAb Sequence Classification

• Annotation Detail Page
• Graphical Representation
• Details Grid
• Annotation Editor
• Add Annotation Type
• Settings/Controls

Annotation Detail Page

To view protein sequence annotations, go to Registry > Protein Sequences, and click a protein id in the Name column. Click the Sequence tab.

• The upper panel represents the sequence graphically, with different annotations called out with colored bars.
• The panel below provides annotation details in a grid view.
• The bottom left panel provides an editor with two tabs for adding and editing annotations.
• The bottom right panel offers controls of the display area

A somewhat simplified version of the annotations viewer is also used within the protein sequence registration wizard.

Graphical Representation

Clicking an annotation’s color bar highlights its description in the grid below, For example, if you click the green bar for sequence position 24-34, that annotation’s details are highlighted in the grid below, and vice versa.

Details Grid

The annotations details grid can be sorted by any of the available columns. The grid will always default to sorting the "Start" column in ascending order

Annotation Editor

The annotation editor has two tabs: Edit Annotation and Add Annotation. Adding or editing an annotation will refresh the grid and viewer to include your changes.

• Note the asterisks marking required fields on the Add Annotation tab. The button at the bottom of the form will remain grayed out until all fields have been filled out.
• The Type dropdown is pre-populated with the items in the list "AnnotationTypes".

In order to edit an annotation, select one from the grid or viewer and click the Edit Annotation tab.

Click the Edit button to enable the field inputs and action buttons:

• Remove Annotation: Removes the annotation and deletes the details row from the grid.
• Cancel: Cancels the edit.
• Save: Save any changes to the selected annotation.

Add AnnotationType

To add a new option to the Annotation Type dropdown, such as "Protease Cleavage Site", switch to the LabKey Server interface and edit the "AnnotationTypes" list. Insert a new row, specifying the name, abbreviation and category you want to use.

This option will now be available on the dropdown when adding or editing annotations.

Settings/Controls

The controls in the bottom right panel let you customize the display region.

• Sequence Length: The length of the entire sequence.
• Line Length: Select to control the display scale. Options: 50, 60, 80, 100.
• Index: Show or hide or show the position index numbers.
• Annotations: Show or hide the annotation color bars.
• Direction: Show or hide the direction indicators on the bars.

Below these controls, you can see a sequence selection widget next to the Copy sequence button. The position boxes for start and end update to the currently selected annotation. These can be manually changed to any index values in the sequence, or can be reset to the full sequence by pressing the refresh icon.

Clicking Copy sequence will copy the indicated segment to your clipboard for pasting (useful when registering a new protein sequence into the Registry).

Related Topics

• Register Protein Sequences
• Register Leaders, Linkers, and Tags
• CoreAb Sequence Classification

This topic describes the methodology developed by Just-Evotec Biologics, Inc for the structural alignment and classification of full sequences from antibodies and antibody-like structures using the Antibody Structural Numbering system (ASN). The classification process generates a series of ASN-aligned regions which can be used to uniquely describe residue locations in common across different molecules.

When you register a new protein sequence, this methodology is used to apply annotations representing these classifications. It will not override information provided in a GenBank file. After import and initial classification using this methodology, you can then refine or add more annotations as needed.

• CoreAb Sequence Classification Introduction
• Classification Process
• Reference Germline Data Extraction Process

CoreAb Sequence Classification: White Paper Introduction

This methodology was published in March 2020, and is also available here:

• https://just-evotecbiologics.com/white-papers-application-notes/coreab-sequence-classification/
• Author: J. Alex Taylor
• Publication: March 2020

Keywords: antibody; antibody numbering; structural numbering; antibody engineering; antibody analysis

Classification Process

The CoreAb Java library (developed at Just - Evotec Biologics) contains algorithms for the classification and alignment of antibodies and antibody-like sequences. A high-level summary of the classification process is presented in Figure 1. The first step in the classification process is the detection of antibody variable and constant regions specified in the detection settings. The default regions for detection are kappa variable, lambda variable, heavy variable, light constant, heavy constant Ig (CH1), heavy constant Fc-N (CH2), and heavy constant Fc-C (CH3). A Position-Specific Sequence Matrix (PSSM) has been pre-built for each type and is used as a low threshold first pass filter for region detection using the Smith-Waterman algorithm to find local alignments. Each local alignment is then refined by a more careful alignment comparison to the germline gene segments from species specified in the detection settings. If germline data for the query’s species of origin does not exist or is incomplete in the resource files contained in CoreAb, other, more complete, germline gene data sets from other species can be used to identify homologous regions. The germline sequences are stored as ASN-aligned so that the resulting region alignments are also ASN-aligned.

To generate an alignment for variable regions, the PSSM-matched sub-sequence is aligned to both germline V-segments and J-segments and these results are combined to synthesize an alignment for the entire variable region. For heavy variable regions, the germine D-segments are aligned to the residues between the V-segment match and the J-segment match. As a final step in the variable region alignment refinement process, CDR regions are center-gapped to match the AHo/ASN numbering system.

Fig. 1 High-level antibody classification pseudocode

1. Identify antibody variable and constant regions (domains)
   a. Loop over the region types that were specified in settings
      i. Use a PSSM for the region type to find local alignments in the query
      ii. Loop over each local alignment from the query
         1. Loop over the germline sets that were specified in settings
            a. Generate a refined region alignment for the PSSM alignment
               i. Only keep alignments that meet the minimum number of identities and 
                   region percent identity specified in settings
               ii. Assign ASN numbering
               iii. If variable region, refine the alignment and adjust CDR gapping
               iv. If constant region and alignment is < 10 aa, toss it unless it is at 
                   the start of the region
2. Identify potential leader region matches (can use SeqParts)
3. Resolve overlapping regions giving priority to the higher scoring region
4. Assign gaps between identified regions (can use SeqParts)
5. Cleanup constant regions
6. Assign chain and structure format (based on the arrangement of regions)

Resulting germline-aligned regions are subjected to minimum percent identity thresholds which can be specified in the detection settings. The default threshold is 80% identity for constant regions and 60% identity for variable region frameworks. Constant region results of less than 10 residues are removed unless they occur at the start of a region. Regions that meet these thresholds are then compared to the other results for the same region and, if overlaps are found, the lower scoring region is removed.

Step 2 of the classification process is the detection of a leader sequence. If, after the variable and constant regions have been detected, there remains an N-terminal portion of the query sequence that is unmatched, the N-terminal portion is aligned to germline leaders from the specified germline gene sets and also to user-specified SeqPart sequences which have been provided to the detector. Resulting leader regions are subjected to a minimum percentage identity threshold which can be specified in the detection settings. The default threshold is 80% identity for leader regions. The highest scoring region result that meets this threshold is retained as the leader region.

In step 3, remaining regions are sorted by their score and then overlaps are resolved by giving preference to the higher scoring region except in cases where the overlapping residues are identities in the lower scoring region and are not identities in the higher scoring region. This step may result in the removal of the lower scoring region.

Step 4 assigns regions to any portions of the query which fall before, between, or after the remaining identified regions. If such regions fall after a constant Ig region or constant Fc-C region, germline hinge or post-constant regions from the germline gene matching the preceding region are respectively aligned to the query subsequence. If the resulting alignment percent identity meets the constant region threshold, the regions are added. Remaining unmatched portions of the query are then compared to

SeqParts if a SeqParts resource has been provided to the detector and resulting regions with a percent identity of greater than or equal to 80% are retained. Any portions of the query that still remain unassigned are assigned to unrecognized regions.

In step 5, the assigned constant region germline genes are harmonized if necessary. In many cases a region may have the same sequence for different alleles. In this step, the overall best scoring germline gene is determined and then any regions that are assigned to another germline gene are checked to determine if the overall best scoring germline has an equivalent score. If so, then the assignment for the region is changed to the overall best scoring germline.

The final step in the sequence classification process is to assign a chain format. If an AbFormatCache is provided to the detector, it is used to match the pattern of regions to a reference pattern associated with a particular chain format. Figure 2 shows a portion of the default AbFormatCache contained in the CoreAb library.

After all sequence chains have been classified they can be grouped into structures, often based on a common base name. An AbFormatCache can then be used to assign a structure format such as IgG1 Antibody or IgG1 Fc-Fusion to the structure by matching the chain formats present in the structure to structure format definitions that are made up of possible combinations of chain formats.

Fig. 2 Snippet of the default AbFormatCache from CoreAb. Three chain format definitions and three structure format definitions are shown. Regions in curly braces are optional.

<AbFormatCache version='2'>
 <ChainFormats>
  ...
    <ChainFormat id='55' name='DVD-IgG1 Heavy Chain' abbrev='DVD-IgG HC' description='DVD-IgG1 Heavy Chain'>
      {Ldr} ; HV ; Lnk ; HV ; IgG1:HCnst-Ig ; IgG1:Hinge ; IgG1:Fc-N ; IgG1:Fc-C ; IgG1:HCnst-Po
    </ChainFormat>
    <ChainFormat id='56' name='IgG1 Fc-Fusion' abbrev='IgG1 Fc-Fusion' description='IgG1 Fc-Fusion'>
      {Ldr} ; Unk ; {Lnk}; IgG1:Hinge ; IgG1:Fc-N ; IgG1:Fc-C ; IgG1:HCnst-Po
    </ChainFormat>
    <ChainFormat id='57' name='IgG1 Heavy Chain F(ab&apos;)2' abbrev='IgG1 HC F(ab&apos;)2' description='IgG1 Heavy Chain F(ab&apos;)2'>
      {Ldr} ; HV ; IgG1:HCnst-Ig ; IgG1:Hinge&lt;C113,C116>
    </ChainFormat>
    ...
  </ChainFormats>

  <StructureFormats>
    ...
    <StructureFormat id='28' name='DVD-IgG1' abbrev='DVD-IgG1' description='Dual Variable Domain (DVD) Bispecific IgG1 Antibody'>
      <ChainCombination>
        <ChainFormat id='53' stoichiometry='2' />
        <ChainFormat id='55' stoichiometry='2' />
      </ChainCombination>
      <ChainCombination>
        <ChainFormat id='54' stoichiometry='2' />
        <ChainFormat id='55' stoichiometry='2' />
      </ChainCombination>
    </StructureFormat>

    <StructureFormat id='29' name='IgG1 Fc-Fusion' abbrev='IgG1 Fc-Fusion' description='IgG1 Fc-Fusion'>
      <ChainCombination>
        <ChainFormat id='56' stoichiometry='2' />
      </ChainCombination>
    </StructureFormat>
    <StructureFormat id='30' name='IgG1 F(ab&apos;)2' abbrev='IgG1 F(ab&apos;)2' description='IgG1 F(ab&apos;)2 Fragment'>
      <ChainCombination>
        <ChainFormat id='5' stoichiometry='2' />
        <ChainFormat id='57' stoichiometry='2' />
      </ChainCombination>
      <ChainCombination>
        <ChainFormat id='8' stoichiometry='2' />
        <ChainFormat id='57' stoichiometry='2' />
      </ChainCombination>
    </StructureFormat>
    ...
  </StructureFormats>
</AbFormatsCache>

Reference Germline Data Extraction Process

The extraction and compilation of antibody germline gene data can be a difficult and time consuming process. In cases where gene annotation is provided by the NCBI, a CoreAb tool is used to extract and align the gene information. Incomplete or unannotated genomes require a more de novo approach. CoreAb also contains a tool that can scan for potential V-segments, J-segments, and D-segments using PSSMs designed to locate the Recombination Signal Sequence (RSS) sequences used to join the variable region segments. Manual curation is still required to filter and adjust the results but this automation can alleviate most of the tedious work. When possible, names for extracted genes are set to those from IMGT since that is the source of official naming. Figure 3 displays a section of an XML-formatted germline data resource file. Default XML-formatted germline data is included in CoreAb and loaded at runtime. Additional or alternate germline data can be provided by the user. Full or partial antibody gene data is currently included in CoreAb for the following organisms: Bos taurus, Camelus bactrianus, Camelus dromedarius, Canis familiaris, Cavia porcellus, Gallus gallus, Homo sapiens, Macaca mulatta, Mus musculus, Oryctolagus cuniculus, Ovis aries, Protopterus dolloi, Rattus norvegicus, Struthio camelus, and Vicugna pacos.

Fig. 3 Snippet of the Bos taurus HV.xml germline data file of heavy variable genes extracted from genomic sequences.

<?xml version='1.0' encoding='UTF-8' standalone='yes' ?>
<GermlineGeneSetRsrc igGeneGroup='IGHV' taxonId='9913'>
  ...
  <GermlineGene id='IGHV1-20*01'>
    <Note>Num RSS mismatches: 0</Note>
    <GenomicLoc build='ARS-UCD1.2' chromosome='21' contig='NW_020190105.1' contigLength='69862954'
strand='Forward'>join(278220..278274,278353..278658)</GenomicLoc>
    <DB_Xref db='Just-TempId'>IGHV1-4S*01</DB_Xref>
    <DB_Xref db='IMGT/GENE-DB'>IGHV1-20*01</DB_Xref>
    <Intron donorSite='a gtgtc' acceptorSite='acag g' seqLength='78'>
      <GenomicLoc build='ARS-UCD1.2' chromosome='21' contig='NW_020190105.1' contigLength='69862954'
strand='Forward'>278275..278352</GenomicLoc>
      <DNA>
        gtgtctctgggtcagacatgggcacgtggggaagctgcctctgagcccacgggtcaccgtgcttctctctctccacag
      </DNA>
    </Intron>
    <AlignedRegions>
      <AlignedRegion region='HLdr'>
        <Protein>
          MNPLWEPPLVLSSPQSGVRVLS
        </Protein>
        <DNA>
          atgaacccactgtgggaacctcctcttgtgctctcaagcccccagagcggagtgagggtcctgtcc
        </DNA>
      </AlignedRegion>
      <AlignedRegion region='HV'>
        <Protein>
          QVQLRES-GPSLVKPSQTLSLTCTVSG-FSLSS-----YAVGWVRQAPGKALEWLGGISS----GGSTYYNPALKSRLSITKDNSKSQVSLSVSSVTPEDTATYYCAK-----------------------------------------
        </Protein>
        <DNA RSS_3prime='cacagtg aggggaaatcagtgtgagcccag acaaaaacc' splitCodon3prime='ga'>
          caggtgcagctgcgggagtcgggccccagcctggtgaagccctcacagaccctctccctcacctgcacggtctctggattctcactgagcagctatgctgtaggctgggtccgccaggctccagggaaggcgctggagtggctcggtggtataagcagtggtggaagcacatactataacccagccctgaaatcccggctcagcatcaccaaggacaactccaagagccaagtctctctgtcagtgagcagcgtgacacctgaggacacggccacatactactgtgcgaagga
        </DNA>
      </AlignedRegion>
    </AlignedRegions>
  </GermlineGene>
  ...
</GermlineGeneSetRsrc>

Related Topics

• Protein Sequence Annotations
• Register Protein Sequences

This topic covers the process of assigning chain and structure formats in Biologics LIMS.

• Overview
• Chain Formats
• Chain Format Syntax
• Structure Formats

Overview

After the classification engine has determined the pattern of regions within the sequence, the chain and structure format information that was provided is used to first match the regions to a chain pattern and then to match the assigned chain formats to a unique structure format.

If antibody regions are present in a ProteinSeq, but it does not match a chain format, it will be assigned a chain format of "Unrecognized Antibody Chain" and the Molecule is assigned a structure format of "Unrecognized Antibody Format".

If no antibody regions are present, the ProteinSeq is assigned a chain format of "Non-Antibody Chain" and the Molecule structure format is set to "Non-Antibody".

In order for changes to the chain and structure formats to take effect, an administrator needs to clear caches from the Administration Console.

Chain Formats

Chain formats are stored in the ChainFormats List.

A chain format specification is specified at the region level using region abbreviations. Recognized regions are listed in the following table.

Chain Format Syntax

1. Regions are separated by a semicolon. Optional regions are surrounded by braces {}.

Example 1: A kappa light chain is specified as:

{Ldr} ; KV ; KCnst-Ig ; {KCnst-Po}

2. OR choices are separated by a '|' and enclosed in parentheses like (A | B) or by braces like {A | B}

Example 2: an scFv is specified as:

{Ldr | Unk<M>} ; (HV ; Lnk ; KV/LmdV | KV/LmdV ; Lnk ; HV)

3. A colon-separated prefix to a region abbreviation indicates a particular germline gene.

Example 3: an IgG2 heavy chain is specified as:

{Ldr} ; HV ; IgG2:HCnst-Ig ; IgG2:Hinge ; IgG2:Fc-N ; IgG2:Fc-C ; IgG2:HCnst-Po

4. A sequence-level specification can be specified after the region abbreviation in '<>'.

Example 4: an IgG1 Heavy Chain Fab is specified as:

{Ldr} ; HV ; IgG1:HCnst-Ig ; IgG1:Hinge<!113-123>

which indicates that ASN positions 113 to 123 should not be present.

5. Example 5: an IgG1 HC Knob-into-Hole + phage + disulfide (Knob) is specified as:

{Ldr} ; HV ; IgG1:HCnst-Ig ; IgG1:Hinge ; IgG1:Fc-N ; IgG1:Fc-C<C15,W30> ; IgG1:HCnst-Po

where ASN position 15 of the Fc-C domain must be a cysteine and position 30 must be a tryptophan.

6. Square brackets are used to indicate which Fv a variable region is a part of.

Example 6: an IgG1 CrossMab CH1-CL Fab Heavy Chain is specified as:

{Ldr} ; HV[3] ; IgG1:HCnst-Ig ; Unk<EPKSCD> ; Lnk ; HV[2] ; Unk<A> ; KCnst/LmdCnst ;
IgG1:Hinge<!1-107> ; IgG1:Fc-N ; IgG1:Fc-C<C15,W30> ; IgG1:HCnst-Po

7. Finally the special character '⊃' is used to specify a particular region subtype. Currently, this is only used to indicate a VHH as a subtype of VH.

Example 7: an IgG1 HCab Chain is specified as:

{Ldr} ; HV⊃VHH ; IgG1:Hinge ; IgG1:Fc-N ; IgG1:Fc-C ; IgG1:HCnst-Po

Structure Formats

Structure formats are stored in the StructureFormats List where the only important information is the name and abbreviation. The more important table is ChainStructureJunction which describes the chain combinations that map to a structure format.

For example, there are two chain combinations for an IgG1, 2 copies of a Kappa Light Chain + 2 copies of an IgG1 Heavy Chain or 2 copies of a Lambda Light Chain + 2 copies of an IgG1 Heavy Chain. In the ChainStructureJunction this is represented like this:

*The Num Distinct column is used to indicate the number of sequence-distinct copies of that chain type. This is normally 1 but there are a few odd formats like a Trioma or Quadroma bi-specific IgG1 where the Num Distinct value might be 2.

**The Fv Num Override column is for the rare situations where because of how the chains are combined, the default Fv Num values in the chain format spec need to be overridden.

For example in a CrossMab CH1-CL Fab, The Fv Num Override value of '1#1/1#3' indicates that for one copy of the Kappa chain the 1st V-region is part of Fv#1 and for the other copy the 1st V-region is part of Fv#3.

Related Topics

• Biologics: Bioregistry

• Definitions
• Molecule Components
• Rules for Entity Calculation/Creation
• Aliases and Descriptions

Definitions

Molecules are composed of various components and have a set of physical properties that describe them. When a molecule is added to the registry, the following additional entities are calculated and added, depending on the nature of the molecule. These additional entities can include:

• Molecular Species
• Molecule Sets
• Other Protein Sequences

Molecular Species serve as alternate forms for a given molecule. For example, a given antibody may give rise to multiple Molecular Species: one Species corresponding to the leaderless, or "mature", portion of the original antibody and another Molecular Species corresponding to its "mature, desK" (cleaved of signal peptides and heavy chain terminal lysine) form.

Both Molecular Species and Sets are calculated and created by the registry itself. Their creation is triggered when the user adds a Molecule to the registry. Users can also manually register Molecular Species, but generally do NOT register their own Molecule Sets. Detailed triggering and creation rules are described below.

Molecule Components

A molecule can be created (= registered) based on one or more of the following:

• a protein sequence
• a nucleotide sequence
• other molecules

Rules for Entity Calculation/Creation

When the molecule contains only protein sequences, then:

• A mature molecular species is created, consisting of the leaderless segments of the protein sequences, provided a leader portion is identifiable. The leader segment has to be:
• Have annotation start with residue #1
• The annotation Type is "Leader"
• The annotation Category is "Region"
• (If no leader portion is identifiable, then the species will be identical to the Molecule which has just been created.)
• Additionally, a mature desK molecular species is created (provided that there are terminal lysines on heavy chains).
• New protein sequences are created corresponding to any species created, either mature, mature des-K, or both. The uniqueness constraints imposed by the registry are in effect, so already registered proteins will be re-used, not duplicated.
• A molecule set is created, provided that the mature molecular species is new, i.e., is not the same (components and sequences) as any other mature molecular species of another molecule. If there is an already existing mature species in the registry, then the new molecule is associated with that set.

• Physical properties are not calculated.
• Molecular species are not created.
• A molecule set is created, which has only this molecule within it.

Aliases and Descriptions

When creating a Molecule, the auto-generated Molecule Set (if there is a new one) will have the same alias as the Molecule. If the new Molecule is tied to an already existing Molecule Set, the alias is appended with alias information from the new Molecule.

When creating a molecule, the auto-generated molecular species (both mature and mature desK) should have the same alias as the molecule. Similarly, when creating a molecular species from a molecule (manually), the alias field will pre-populate with the alias from the molecule.

For molecular species that are auto-generated, if it is creating new protein sequences (one or more) as the components of that molecular species, they have a Description:

• Mature of “PS-15”
• Mature, desK of “PS-16”

• Mature of “PS-17”
• Mature, desK of “PS-18”

Related Topics

• Register Molecules
• Molecular Physical Property Calculator

This topic shows how to register a new molecule using the graphical user interface. To register molecules in bulk via file import, see Create Registry Sources.

• Create a Molecule
• Add Details
• Select Components
• Stoichiometry
• Confirm

• Bulk import molecules from an Excel spreadsheet
• Register using the API

Create a Molecule

To add a new molecule to the registry:

• Open the Molecules creation wizard.

Add Details

On the first tab of the wizard, enter the following:

• Name: Provide a name, or one will be generated for you. Hover to see the naming pattern
• Description: (Optional) A text description of the molecule.
• Alias: (Optional) Alternative names for the molecule.
• Common Name: (Optional) The common name of the molecule, if any.
• Molecule Parents: (Optional) Parent molecules for the new molecule.

Click Next to continue.

Select Components

• On the Select components tab, search and select existing components of the new molecule.
• After selecting the appropriate radio button, search for the component of interest.
• Type ahead to narrow the list.
• You will see a details preview panel to assist you.

• Once you have added a component, it will be shown as a panel with entity icon. Click the to expand details.

Click Next to continue.

Stoichiometry

LabKey Biologics will attempt to classify the structure format of the molecule's protein components, if possible. The structure format is based on the component protein chain formats.

On the Stoichiometry pane enter:

• Stoichiometry from each component
• Structure Format: Select a format from the pulldown list. The list is populated from the StructureFormat table.

Click Next to continue.

Confirm

On the final tab, confirm the selections and click Finish to add the molecule to the registry.

The new molecule will be added to the grid.

Related Topics

• Bulk Registration of Entities
• Use the Registry API
• Register Nucleotide Sequences
• Register Protein Sequences
• Vectors, Constructs, Cell Lines, and Expression Systems

Antibody discovery, engineering, and characterization work involves a great deal of uncertainty about the materials at hand. There are important theoretical calculations necessary for analysis as well as variations of molecules that need to be explored. Scientists want to consider and run calculations several different ways based on variations/modifications they are working with for analysis and inclusion in a notebook.

In the case of a structure format not being recognized, e.g. some scFv diabody, it will not be properly classified and the calculations will be wrong. Providing the ability to reclassify and recalculate molecular physical properties is key for assisting with scenarios such as "What if this S-S bond formed or didn’t?"

Using the built-in Molecular Physical Property Calculator, you can view the persisted calculations to make your input conditions and calculation type clearer and select alternative conditions and calculations for your entity.

We currently calculate average mass, pI (isoelectric point), and 𝜺 (extinction coefficient) from the sequence, molecular stoichiometry, number of free Cysteine and disulfide bonds. While including stoichiometry, free Cys vs S-S, these inputs include sequence scope/type.

• View Physical Property Calculator
• Calculation Inputs
• Properties
• Export Calculations

View Physical Property Calculator

From the grid of Molecules, select the Molecule of interest. Click the Physical Property Calculator tab.

Calculation Inputs

In the Calculation Inputs panel, you'll enter the values to use in the calculation:

• Num. S-S: Dynamically adjusted to be half of the "Num. Cys" value.
• Num Cys: A display only value derived from the sequence chosen.
• Sequence Scope: Select the desired scope. Sequence ranges will adjust based on your selection of any of the first three options. Use "Custom Range" for finer control of ranges.
• Full Protein Sequence: complete amino acid sequence of a protein, including all the amino acids that are synthesized based on the genetic information.
• Mature Protein Sequence: final, active form of the protein, after post-translational modifications and cleavages, or other changes necessary for the protein to perform its intended biological function.
• Mature Des-K Protein Sequence: mature protein sequence with the C-Terminal Lysine removed.
• Custom Range
• Sequence Ranges for each component sequence. These will adjust based on the range selected using radio buttons, or can be manually set using the "Custom Range" option.
• Use Range: Enter the start and end positions.
• Click View this sequence to open the entire annotated sequence in a new tab for reference.
• Stoichiometry
• Analysis Mode. Select from:
• Native
• Reduced
• Alkylated Cysteine (only available in "Reduced" mode). If available, select the desired value.
• Modifiers
• Pyro-glu: Check the box for "Cyclize Gln (Q) if at the N-terminus"
• PNGase: Check the box for "Asn (N) -> Asp (D) at N-link sites"

Properties

When you click Calculate, the right hand panel of Properties will be populated. You'll see both what the Classifier Generated value is (if any) and the Simulated value using the inputs you entered.

Calculations are provided for:

• Mass
• Average Mass
• Monoisotopic Mass
• Organic Average Mass
• pI - Isoelectric Point calculated by different methods:
• Bjellqvist
• EMBOSS
• Grimsley
• Patrickios (simple)
• Sillero
• Sillero (abridged)
• Other
• Chemical Formula
• Extinction Coefficient - ε
• Percent Extinction Coefficient
• Sequence Length
• Amino Acid (AA) composition

Export Calculations

To export the resulting calculated properties, click Export Data.

The exported Excel file includes both the calculated properties and the inputs you used to determine them. For example, the export of the above-pictured M-17 calculation would look like this:

Related Topics

• Molecules, Sets, and Molecular Species

The Biologics LIMS Registry includes a Compound registry source type to represent data in the form of Simplified Molecular Input Line Entry System (SMILES) strings, their associated 2D structures, and calculated physical properties. This data is stored in LabKey Biologics not as a system of record, but to support analysis needs of scientists receiving unfamiliar material, analytical chemists, structural biologists, and project teams.

• SMILES Lookup Field
• Create/Import Compounds
• Create Compound: Carbon Dioxide
• Import File of SMILES Strings

The SMILES information succinctly conveys useful information about the structure(s) received when shared with others, helping structural biologists quickly view/reference the Compound structure and properties while trying to model a ligand. Analytical chemists can use the Compound calculated physical properties for accurate measurements and calculations. For many project team members, the SMILES structure is often used in reports and presentations as well as to plan future work.

SMILES Lookup Field

The Compound registry source type uses a custom SMILES field type only available in the Biologics module for this specific registry source. This datatype enables users to provide a SMILES string, e.g. "C1=CC=C(C=C1)C=O", that will return a 2D structure image, molecular weight and other computed properties.

The SMILES string is used to search the Java library CDK ("Chemistry Development Kit") , a set of open source modular Java libraries for Cheminformatics. This library is used to generate the Structure2D image and calculate masses.

Create/Import Compounds

New Compounds can be created manually or via file import. It's easier to get started understanding the lookup process by creating a single compound in the user interface.

Create Compound: Carbon Dioxide

As an example, you could create a new compound, supplying the SMILES string "O=C=O" and the Common Name "carbon dioxide".

The SMILES string will be used to populate the Structure2D, Molecular Formula, Average Mass, and Monoisotopic Mass columns.

Click the thumbnail for a larger version of the Structure2D image. You can download the image from the three-dot menu.

Import File of SMILES Strings

When a file of SMILES strings is Created/imported, each is used to query for the respective 2D structure, molecular weight and set of computed properties. During the Create/Import operation if Name/ID isn’t specified, the SMILES string is used for Name.

Related Topics

• Create Registry Sources
• Biologics: Bioregistry
• CDK (Chemistry Development Kit) : Open Source modular Java libraries for Cheminformatics

• View Lineage
• Lineage Graph
• Graph Filters for Samples
• Lineage Grid
• Troubleshooting

View Lineage

Any parents and children of an Registry Source or Sample can be viewed by clicking the Lineage tab on the details page.

The main lineage dashboard shows a graphical panel on the left and details on the right.

Two lineage views are available: (1) a graphical tree and (2) a grid representation.

Lineage Graph

The graphical tree shows parents above and children below the current entity. Click any node in the tree to see details on the right. Hover for links to the overview and lineage of the selected node, also known as the seed.

• Zoom out and in with the and buttons in the lower left.
• Step up/down/left and right within the graph using the arrow buttons.
• Up to 5 generations will be displayed. Walk up and down the tree to see further into the lineage.
• Click anywhere in the graph and drag to reposition it in the panel.
• Refresh the image using the button. There are two options:
• Reset view and select seed
• Reset view

Graph Filters for Samples

When viewing lineage for Samples, you will have a filter button. Use checkboxes to control visibility in the graph of derivatives, source parents, and aliquots.

Lineage Grid

Click Go to Lineage Grid to see a grid representation of lineage. The grid view is especially helpful for viewing lengthy lineages/derivation histories. Control visibility of parents and children in the grid view using Show Parents and Show Children respectively.

Items in the Name column are clickable and take you to the details page for that entity.

Arrow links in the Change Seed column reset the grid to the entity in the Name column, showing you the parents or children for that entity.

Troubleshooting

Note that if any entity names that just strings of digits, you may run into issues if those "number-names" overlap with row numbers of other entities of that type. In such a situation, when there is ambiguity between name and row ID, the system will presume that the user intends to use the value as the name.

Related Topics

• Lineage Navigation in Sample Manager

This topic covers how an administrator can create new Registry Source Types in the Bioregistry and edit the fields in the existing Registry Source Types, including all built in types and, in the Enterprise Edition, Media definitions.

• Definitions
• Edit Existing Registry Source Types
• Create New Registry Source Type
• Lineage for Custom Registry Source Types
• Delete Custom Registry Source Type

Definitions

The term Registry Source Type applies to all of the following entities in the Biologics application. These are two of the categories of Data Class available in LabKey Server. Within the Biologics application you cannot see or change the category, though if you access these structures outside the application you will be able to see the category.

• Registry Source Types: (Category=registry)
• CellLine
• Construct
• ExpressionSystem
• MolecularSpecies
• Molecule
• MoleculeSet
• NucSequence
• ProtSequence
• Vector
• Media Types: (Category=media)
• Ingredients
• Mixtures

Edit Existing Registry Source Types

The default set of Registry Source and Media Types in Biologics are designed to meet a common set of needs for properties and fields for the Bioregistry and Media sections.

If you want to customize these designs, you can edit them within the Biologics application following the same interface as used for Sample Manager "Sources".

Open the desired type from the main menu. All entries under Registry Sources and Media are editable. Select Manage > Edit [Registry Source Type] Design.

You can edit the Name, Description, and Naming Pattern if desired. Note that such changes to the definition do not propagate into changing names of existing entities. For custom Registry Source Types, you can also add or update lineage.

Click the Fields section to open it. You'll be able to adjust the fields and their properties here. Any field properties that cannot be edited are shown read only, but you may be able to adjust other properties of those fields.

When finished click Finish Editing Source Type in the lower right.

Create New Registry Source Type

From the main menu, click Registry Sources. Click Create Source Type.

Follow the same process as for creating Sources in Sample Manager.

It is best practice to use a naming pattern that will help identify the registry type. Our built in types use the initials of the type (like CL for Cell Lines).

• For example, to use "DC-" followed by the date portion of when the entity is added, plus an incrementing number you could use:

  DC-${now:date}-${genId}

Click the Fields section to open it. You'll see Default System Fields, and can import, infer, or manually define the fields you need using the field editor.

When finished, click Finish Creating Source Type. Your new class will now appear on the registry dashboard and can have new entities added as for other Registry Source types.

{anchor:name=lineage">here

Lineage for Custom Registry Source Types

The lineage relationships among the built-in Registry Source Types are pre-defined. Learn more in this topic: Biologics: Terminology

When you create your own Custom Registry Source Types, you can include Parent Aliases in the definition, making it possible to define your own lineage relationships.

To add a new lineage relationship, either define it when you create the new Registry Source Type or edit it later.

Delete Custom Registry Type

You cannot delete the built in Registry Source Types, but if you add a new custom one, you will have the ability to delete it. Before deleting the type, you may want to delete all members of the type. If any members are depended upon by other entities, deletion will be prevented, allowing you to edit to change the connections before deleting the type.

• Select the custom type to delete from the Registry section of the main menu.
• Select Manage > Delete [Registry Source Type].

Deleting a Registry Source Type cannot be undone and will delete all members of the type and data dependencies as well. You will be asked to confirm the action before it completes, and can enter a comment about the deletion for the audit log.

Related Topics

• Biologics: Bioregistry
• Create Registry Sources

Many entity types can be uploaded in bulk using any common tabular format. Protein and nucleotide sequences can be imported using the GenBank format.

Upon upload, the Registry will calculate and create any molecular species and sets as appropriate.

• Assemble Bulk Entity Data
• Indicate Lineage Relationships
• Bulk Upload Entity Data
• Bulk Data Example Files

Supported File Formats

The file formats supported are listed in the file import UI under the drop target area.

Tabular file formats are supported for all entity types:

• Excel: .xls, .xlsx
• Text: .csv, .tsv

• GenBank: .genbank, .gb, .gbk

Assemble Bulk Data

When assembling your entity data into a tabular format, keep in mind that each Registry Source Type has a different set of required column headings.

• Acquire a template Excel file for a given entity by clicking Template from the Registry Source Type overview page.
• Open the Excel file, and add data as appropriate under the column headers. See examples below.

Indicate Lineage Relationships

Lineage relationships (parentage) of entities can be included in bulk registration by adding "DataInputs/<DataClassType>" columns and providing parent IDs.

For example, to include a Vector as a 'parent' for a bulk registered set of Expression Systems, after obtaining the template for Expression Systems, add a new column named "DataInputs/Vector" and provide the parent vector name for each row along with other fields defining the new Expression Systems.

Bulk Upload Registry Source Data

After you have assembled your information into a table, you can upload it to the registry:

• Go the Registry Source Type you wish to import.
• Select Add > Import from File.
• On the import page, you can download a template if you don't have one already, then populate it with your data.
• Confirm that the Source Type you want is selected, then drag and drop your file into the target area and click Import.

If you want to update existing registry sources or merge updates and creation of new sources, use Edit > Update from File.

Bulk Data Example Files

Example Nucleotide Sequence File

Notes:

• Annotations: Add annotation data using a JSON snippet, format is shown below.

[  
   {  
      name:"First Annotation",
      category:"Feature",
      type:"Leader",
      start:1,
      end:20
   },
   {  
      name:"Another Annotation",
      category:"Feature",
      type:"Constant",
      start:30,
      end:50
   }
]

When importing the rows for NucSequence, you can reference the corresponding ProtSequence and the translation start, end, and offset. (The offsets are 1-based.) An example:

Example Protein Sequence File

Notes:

• Organisms: A comma separated list of applicable organisms. The list, even if it has only one member, must be framed by square brackets. Examples: [human] OR [human, rat, mouse]
• ?: The column header for the extinction coefficient (ε).
• %?: The column header for the % extinction coefficient (%ε).

Mixtures and Batches

The text 'unknown' can entered for certain fields. For Mixtures, the Amount field; for Mixture Batches, the Amount and the RawMaterial fields.

Mixture Bulk Upload

Batch Bulk Upload

Related Topics

• GenBank Format
• Create Entity via File Upload

This topic covers ways to register entities outside the LabKey Biologics application, either directly via the API or using the LabKey Server manual import UI to load data files.

• Identity Service
• Manual Data Entry
• Register via Query API
• Lineage, Derivation, and Samples

Identity Service

When registering a sequence or molecule, use the identity of the sequence to determine uniqueness. External tools can use the following API to get the identity of a sequence prior to registration. To get the identity of a sequence use either the identity/get.api or identity/ensure.api. The ensure.api will create a new identity if the sequence hasn't been added yet.

To get or ensure the identity of a single nucleotide sequence:

LABKEY.Ajax.request({
    url: LABKEY.ActionURL.buildURL("identity", "get.api"),
    jsonData: {
        items: [{
            type: "nucleotide", data: "GATTACA"
        }]
    }
});

To get or ensure the identity of a collection of sequences:

LABKEY.Ajax.request({
    url: LABKEY.ActionURL.buildURL("identity", "get.api"),
    jsonData: {
        items: [{
            type: "nucleotide", data: "GATTACA"
        },{
            type: "protein", data: "ELVISLIVES"
        }]
    }
});

To get or ensure the identity of a molecule containing multiple protein sequences:

LABKEY.Ajax.request({
    url: LABKEY.ActionURL.buildURL("identity", "get.api"),
    jsonData: {
        items: [{
            type: "molecule", items: [{
                type: "protein", data: "MAL", count: 2
            },{
                type: "protein", data: "SYE", count: 3
            ]}
        }]
    }
});

Manual Data Entry

You can enter molecules, sequences, cell lines, etc., using registration wizards within the Biologics application. For an example use of the wizard, see Register Nucleotide Sequences

Cut-and-Paste or Import from a File

The LabKey import data page can also be used to register new entities. For example, to register new nucleotide sequences:

• Go to the list of all entity types (the DataClasses web part).
• Click NucSequence.

• In the grid, select > Import Bulk Data.

• Click Download Template to obtain the full data format.
• Upload an Excel file or paste in text (select tsv or csv) matching the downloaded template. It might be similar to:

When importing a nucleotide sequence with a related protSeqId using the protein sequence's name, you will need to click the Import Lookups By Alternate Key checkbox on the Import Data page. The Name column may be provided, but will be auto-generated if it isn't. The Ident column will be auto-generated based upon the sequence.

To register new protein sequences:

• Go to the list of all entity types
• Click ProtSequence
• In the grid, select > Import Bulk Data.
• Click Download Template to obtain a template showing the correct format.
• Paste in a TSV file or upload an Excel file in the correct format. It might be similar to:

To register new molecules:

• Go to the list of all entity types
• Click Molecule
• In the grid, select > Import Bulk Data.
• Paste in data of the format:

Note that the set of components is provided as a JSON array containing one or more sequences, chemistry linkers, or other molecules. The JSON object can refer to an existing entity by name (e.g "NS-1" or "PS-1") or by providing the identity of the previously registered entity (e.g., "ips:1234" or "m:7890"). If the entity isn't found in the database, an error will be thrown -- for now, all components must be registered prior to registering a molecule.

Register via Query API

The client APIs also can be used to register new entities.

Register Nucleotide Sequence

From your browser's dev tools console, enter the following to register new nucleotide sequences:

LABKEY.Query.insertRows({
  schemaName: "exp.data",
  queryName: "NucSequence",
  rows: [{
    description: "from the client api",
    sequence: "gattaca"
  },{
    description: "another",
    sequence: "cattaga"
  }]
});

Register Protein Sequence

To register new protein sequences:

LABKEY.Query.insertRows({
  schemaName: "exp.data",
  queryName: "ProtSequence",
  rows: [{
    name: "PS-100",
    description: "from the client api",
    chainFormatId: 1,
    sequence: "ML"
  }]
});

Register Molecule

To register new molecules:

LABKEY.Query.insertRows({
  schemaName: "exp.data",
  queryName: "Molecule",
  rows: [{
    description: "from the client api",
    structureFormatId: 1,
    components: [{
        type: "nucleotide", name: "NS-202"
    }]
  },{
    description: "another",
    structureFormatId: 1,
    components: [{
      type: "protein", name: "PS-1"
    },{
      type: "protein", name: "PS-100", count: 5
    }]
  }]
});

Lineage, Derivation, and Samples

Parent/child relationships within an entity type are modeled using derivation. For example, the Lineage page for this nucleotide sequence (NS-3) shows that two other sequences (NS-33 and NS-34) have been derived from it.

To create new children, you can use the "experiment/derive.api" API, but it is still subject to change. The dataInputs is an array of parents each with an optional role. The targetDataClass is the LSID of the entity type of the derived datas. The dataOutputs is an array of children each with an optional role and a set of values.

LABKEY.Ajax.request({
  url: LABKEY.ActionURL.buildURL("experiment", "derive.api"),
  jsonData: {
    dataInputs: [{
      rowId: 1083
    }],
   

    targetDataClass: "urn:lsid:labkey.com:DataClass.Folder-5:NucSequence",
    dataOutputs: [{
      role: "derived",
      values: {
        description: "derived!",
        sequence: "CAT"
      }
    }]
  }
})

Samples will be attached to an entity using derivation. Instead of a targetDataClass and dataOutputs, use a targetSampleType and materialOutputs. For example:

LABKEY.Ajax.request({
  url: LABKEY.ActionURL.buildURL("experiment", "derive.api"),
  jsonData: {
    dataInputs: [{
      rowId: 1083
    }],
   

    targetSampleType: "urn:lsid:labkey.com:SampleType.Folder-5:Samples",
    materialOutputs: [{
      role: "sample",
      values: {
        name: "new sample!",
        measurement: 42
      }
    }]
  }
})

Register Parents/Inputs

To indicate parents/inputs when registering an entity, use the columns "DataInputs/<DataClassName>" or "MaterialInputs/<SampleTypeName>". The value in the column is a comma separated list of values in a single string. This works for both DataClass and SampleType:

LABKEY.Query.insertRows({
    schemaName: "exp.data",
    queryName: "MyDataClass",
    rows: [{
        name: "blush",
        "DataInputs/MyDataClass": "red wine, white wine"
    }]
});

The following example inserts into both parents and children into the same sample type:

LABKEY.Query.insertRows({
	schemaName: "samples",
	queryName: "SamplesAPI",
	rows: [{
		name: "red wine"
	},{
		name: "white wine"
	},{
		name: "blush",
		"MaterialInputs/SamplesAPI": "red wine, white wine"
	}]
});

Related Topics

• Register Nucleotide Sequences

Biologics LIMS supports antibody screening and characterization workflows with integrated Plates and Plate Sets. Capture plate well metadata and explore relationships with samples, registry sources, and sequences.

• Plate Management for Antibody Discovery Workflows

Plates Dashboard

Click Plates (under Sample Types) on the main menu. You can also go directly to Plate Sets or Plate Templates from here.

Plate Sets

See existing plate sets and:

• Create Plate Set
• Manage > Archive
• Manage > Plate Templates

Plate Templates

Plate templates let you set out some common features and well roles for given campaigns.

Related Topics

• Plate Management for Antibody Discovery Workflows
• Biologics LIMS
• samples

Assay data is captured using Assay Designs which include fields for capturing experimental results and metadata about them.

Documentation

Learn more about using the general assay framework in the Sample Manager documentation here:

• Experiment and Assay Data
• Describe Assay Data Structure
• Import Assay Data
• Manage Assay Designs
• Manage Assay Data

Additional Features with LabKey LIMS

• LIMS: Charts

Additional Features with Biologics LIMS

• Use Specialty Assays
• Include File Field Data with Assay Results
• Integrate Assay Data with Bioregistry Entities
• Assay Batch Fields
• Use Assay QC States

Assay data is captured using Assay Designs. Each Assay Design includes fields for capturing experimental results and metadata about them. Once a design has been created, many runs of data matching that format can be imported with the same design.

Learn more in the Sample Manager documentation here:

• Describe Assay Data Structure

• Create a New Assay Design
• Select the Assay Type

Create a New Assay Design

To create a new assay design in Biologics LIMS, follow this process. Make sure to start from the container where you want to define the assay.

• From the main menu, click Assays, then click Create Assay Design.

Select the Assay Type

• Select the Assay Type. For most cases, leave the Standard Assay tab selected.
• Learn more about using Specialty Assays in this topic: defineAssaySchema.
• Click Choose Standard Assay.

• Creating a standard assay in Biologics is the same as described in the Sample Manager documentation here:
• Describe Assay Data Structure
• Creating specialty assays follows a similar process. Specific properties of the specialty assays can be found in this section:
• Assay Types

Related Topics

• Describe Assay Data Structure
• Sample Manager Documentation for Assays

Assay designs can pull in Entity information from any of the DataClasses that have been defined. For example, assay data can refer to related Molecules, Sequences, Components, etc, in order to provide context for the assay results. This topic describes how an administrator can integrate Assay data with other Biologics Entities in the Registry and provide integrated grids to the users.

• Connect Assays with Samples
• Connect Assays with Other Entities
• Create Integrated Grid Views

Connect Assays with Samples

To associate assay data with corresponding samples, include a field of type Sample in the run or result fields. You can name the field as you like and decide whether to allow it to be mapped only to a specific sample type, or to "All Samples".

Learn more in the Sample Manager documentation.

Connect Assays with Other Entities

To add Entity fields to an assay design, add a field of type Lookup that points to the desired Entity/DataClass. For example, the screenshot below shows how to link to Molecules.

Create Integrated Grid Views

Once the assay design includes a lookup to a Sample or another Entity type (such as a Molecule), you can add other related fields to the assay design using Views > Customize Grid View.

Learn about customizing and using grid views in the Sample Manager documentation.

Related Topics

• LIMS: Charts
• Custom Grid Views

Within the Biologics application, you can import assay data from a file or by entering values directly into the grid. Both individual run and bulk insert options are available. You can also initiate assay data import from a grid of samples, or from a workflow job, making it easy to enter data for specific samples.

• Import Assay Data
• Import Assay Data Associated with Selected Samples
• Re-import a Run
• Delete Assay Runs

Import Assay Data

From the main menu, under Assays, click the name of the assay design you wish to import into.

Follow the same general process as for importing assay data into Sample Manager described here. Some additional notes apply:

• Batch Details: If the assay design includes batch fields, you will be prompted to enter values for them.
• When importing Results, if your assay design includes File fields, you can simultaneously upload the referenced files in a second panel of the file upload tab.

Import Assay Data Associated with a Sample

An alternative way to import assay data lets you directly associate assay data with some sample(s) in the registry.

From the Samples grid, select one or more samples, and then select Assay (on narrower browsers this will be a section of the More > menu). Expand the Import Assay Data section, then click the [Assay Design Name]. Scroll to select, or type into the filter box to narrow the list.

The assay import form will be pre-populated with the selected samples, as shown below.

Enter the necessary values and click Import.

Re-Import Run

In cases where you need to revise assay data after uploading to the server, you can replace the data by "re-importing" a run.

To re-import a run of assay data:

• Go the details page for the target run. (For example, go to the runs table for an assay, and click one of the runs.)
• Click the Manage menu and select Re-import Run.

• For instrument-specific assay designs (such as NAb and Luminex), you will be directed to the specific assay’s import page in LabKey Server. Follow the procedure for re-import as dictated by the assay type: Reimport NAb Assay Run or Reimport Luminex Run.
• For general purpose assay designs, you will stay within the Biologics application:
• Revise batch and run details as needed.
• Enter new Results data. The first few lines of the existing results are shown in a preview. Choose Import Data from File or Enter Data Into Grid as when creating a new run.
• Click Re-Import.
• The data replacement event is recorded by the "Replaced By" field.

Delete Assay Runs

To delete one or more assay runs, you can:

• Start from the run details and select Manage > Delete Run.
• From the grid of Runs for the assay, select the run(s) to delete, then choose Edit > Delete.

Learn about editing and deleting individual results rows within a run in the Sample Manager documentation here.

Related Topics

• Manage Assay Data
• Biologics: Assay Data

LabKey Biologics LIMS offers a number of different ways to work with assay data in the system beyond that offered by the Sample Manager and LabKey LIMS products.

• Assay Batch Fields
• Assay Quality Control (QC States)

Assay Batch Fields

Click the name of an Assay Design to see it's summary page, with several tabs, showing various scopes of the data. In addition to Runs and Results, assays in Biologics LIMS may also have fields (and a tab) for Batches of runs.

Assay Quality Control

Visibility of assay data in Biologics can be controlled by setting quality control states. While an admin can edit assay designs to use QC states within the Biologics application, the actual states themselves cannot be configured in the application.

Set Up QC States (Administrator)

To configure states, an admin must:

• Open the Assay Design where you want to use QC. Select Manage > Edit Design.
• Confirm that the QC States checkbox is checked. If not, check it and click Finish Updating [Assay Design Name].
• Use > LabKey Server > [current Biologics folder name] to switch interfaces.
• Configure the available QC states in the system, using this topic: assayQCconfig.
• Select > Manage Assays.
• Click the name of your assay design.
• Select QC State > Manage states.
• Define the states you want to use.
• Once complete, use > LabKey Biologics > [current Biologics folder name] to return to Biologics.

Use QC States (Users)

• When a user has both Reader and QC Analyst roles
• When a user has either Folder-, Project-, or Site Administrator roles

• Navigate to the assay run view page. (Cell Viability runs are shown below.)
• Select one or more runs.
• Select Edit > Update QC States.

• In the popup dialog, use the dropdown menu to select the QC state. This state will be applied to all of the runs selected.
• Optionally add a comment.
• Click Save changes.

• The QC states will be reflected in the runs data grid. Admins and QC Analysts will see all of the runs, as shown below.

• It should be noted that if some of the QC states are not marked as "Public Data", they will not be included in the grid when viewed by non-admin users. For example, if "Not Reviewed" were marked as not public, the reader would see only the runs in public states:

Related Topics

• assayQCconfig
• Biologics: Upload Assay Data

The following topics explain how to manage media and raw ingredients within LabKey Biologics.

Definitions

• Ingredients are virtual entities in LabKey Biologics, and capture the fixed natural 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. Ingredients are managed with an interface similar to Registry Sources.
• Raw Materials are the particular physical instantiations of an Ingredient as real "samples" or "bottles". You register multiple bottles of the Raw Material Sodium Chloride, each with different amounts, sources, lot numbers, locations, vessels, etc. Raw Materials are managed using the Sample Type interface.
• Mixtures are recipes that combine Ingredients using specific preparation steps. Mixtures are virtual entities in LabKey Biologics. Each Mixture is registered only once, but are realized/instantiated multiple times by Batches. Mixtures are managed with an interface similar to Registry Sources.
• Batches are realizations of a Mixture recipe. They are physically real formulations produced by following the recipe encoded by some Mixture. Multiple Batches of the same Mixture can be added to the registry, each with its own volume, weight, vessel, location, etc. Batches are managed using the Sample Type interface.

Deletion Prevention

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.

Topics

• Managing Ingredients and Raw Materials
• Registering Mixtures (Recipes)
• Registering Batches

• Definitions
• Ingredients
• Add a New Ingredient using a Wizard
• Work with Ingredients
• Ingredient Details
• Raw Materials
• Aliquot Raw Materials
• Deletion Prevention

Definitions

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. Defining and creating ingredients uses the Sources UI.
• 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. Defining and creating raw materials uses the Samples UI.

• Mixtures are definitions. Recipe definitions, instructions for combining Ingredients. Mixtures are defined using a wizard but otherwise similar in structure and menus to Sources.
• Batches are physical things, what you get when you combine Raw Materials according to some Mixture recipe. Batches are defined using a wizard but otherwise similar in structure and menus to Samples.

Select Media from the main menu to view the dashboard and manage:

• Ingredients
• Raw Materials

Ingredients

Clicking Ingredients 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, with options similar to those for Sources.

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.
• Derive Samples:
• Select one or more parent ingredients, click Derive Samples, then choose which type of sample to create.
• Reports:
• 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.

Ingredient Details

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.

Raw Materials

The raw materials used in mixtures are listed on the Raw Materials tab.

Defining and creating raw materials uses the Samples UI.

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 more in the Sample Manager documentation here:

• Aliquots, Derivatives, and Sample Pooling

Deletion Prevention

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.

Related Topics

• Registering Mixtures (Recipes)
• Registering Batches

• Registering Mixtures
• Register a Mixture: Wizard Steps
• Register a Mixture using 'Bulk' Ingredients Table
• Registering Mixtures with Unknown Ingredients, Amounts, or Concentrations
• Delete a Mixture
• Use the Recipe API to Update Mixtures

Definitions

• Mixtures are recipes that combine Ingredients using specific preparation steps. Mixtures are virtual entities in LabKey Biologics. Each Mixture is registered only once, but are realized/instantiated multiple times by Batches.
• Batches are realizations of a Mixture recipe. They are physically real formulations produced by following the recipe encoded by some Mixture. Multiple Batches of the same Mixture can be added to the registry, each with its own volume, weight, vessel, location, etc.

Registering Mixtures

The virtual recipes are listed in the Media > Mixtures grid. Find a given Mixture by filtering, sorting, or searching the grid.

Mixtures are comprised of Ingredients and specific preparation details in a "recipe" that can be registered. There are several ways to reach the mixture creation wizard:

• Create a new mixture "from scratch"
• Create a new mixture starting from an existing mixture or ingredient

• Registering Mixtures with Unknown Ingredients, Amounts, or Concentrations.
• Registering Batches with Unknowns.

• Register a Mixture using 'Bulk' Ingredients Table

Start a New Mixture "From Scratch"

Start from an Existing Ingredient or Mixture

Any of the registered ingredients or mixtures can be clicked for a detailed view. The details view includes general information. Mixture detail pages show the mixture’s included ingredients and preparation steps.

Select Manage > Create Mixture. The Ingredients tab will be prepopulated.

Register a Mixture: Wizard Steps

The new mixture wizard adds a new mixture to the registry, and performs a check to ensure that the mixture name is unique in the registry. Duplicate mixture names are not allowed in the registry.

Wizard Step 1: Details

The Details step asks for basic information about the mixture, including a type such as powder or solution. Once all required fields have been filled in, the Next button will become clickable.

Upon clicking Next, the mixture name is checked against the registry to see if it is already in use. A warning displayed if a duplicate name is found.

Wizard Step 2: Ingredients

The Ingredients step allows you to add single ingredients or existing mixtures to a new mixture recipe, as well as the required amounts and the amount unit. If you started the wizard from an ingredient or mixture it will be prepopulated here.

Specify what Recipe Measure Type the mixture is using: Mass or Volume. This selection dictates what unit types are available for the ingredients below.

• If Mass is selected, unit types will be: g/kg, g/g, mL/kg, mol/kg, mol/g, S/S
• If Volume is selected, unit types will be: g/kL, g/L, L/L, mL/L, mol/kL, mol/L, μL/L, μL/mL

Click Add Ingredient for each unique component of the mixture.

Under Type select either Ingredient or Mixture. The Ingredient/Mixture text boxes are 'type ahead' searches, that is, as you type, the registry will offer a filtered dropdown of options that contain your typed string. To control how many fields are shown with each option, you can provide a lookup view.

When at least one ingredient/mixture and the associated amount/amountUnit fields have been filled in, the Next button becomes enabled. If a selected Ingredient or Mixture is no longer desired, the red X button on the left can be clicked to remove it.

Wizard Step 3: Preparation

The preparation step lets you add one or more preparation instructions. Click Add Step to add one or more text boxes. When all instructions have been entered, click the Next button.

Wizard Step 4: Confirmation

The confirmation step summarizes all of the information entered so far.

Click Finish to submit; the mixtures grid is shown with the new addition.

Register a Mixture using 'Bulk' Ingredients Table

This method of registering a mixture lets you enter the ingredients in a tabular format by copying-and-pasting from an Excel or TSV file.

• Go to the Mixtures grid and click Add.
• On the Details tab, enter the Mixture Name and Mixture Type (and description and aliases if needed) then click Next.
• On the Ingredients tab, click Bulk Upload.

• A popup window appears showing the table headers which you can copy-and-paste into an empty Excel file.
• Fill out the table, adding separate lines for each ingredient in the mixture. Only the "Ingredient/Mixture" column is required. If a cell is left blank, you can complete the details of the mixture using the user interface.
• Type: (Optional) Specify either "Ingredient" or "Mixture".
• Ingredient/Mixture: (Required) The name of the ingredient or mixture which must be a pre-existing item already in the registry. Values from the Name or Scientific Name columns are supported.
• Amount: (Optional) A number that indicates the weight or volume of the ingredient.
• Unit Type: (Optional) Possible values are the same as when entering ingredients in the UI.
• Select whether to:
• Append new ingredients or
• Replace ingredients already listed.
• Copy-and-paste the table back into the popup window and click Add Ingredients.

• Fill in any remaining fields, if necessary, and click Next.
• Complete the rest of the mixture wizard.

Registering Mixtures with Unknown Ingredients, Amounts, or Concentrations

In cases where you do not know the exact ingredients, amounts, or concentrations of a material, you can still add it to the registry. These scenarios are common when receiving a material from an outside vendor who does not disclose the exact formulation of the product.

In such cases, the mixture registration process is largely the same, except for the Ingredients step, where you can toggle all ingredients and amounts as unknown, or toggle individual amounts as unknown.

Clicking Unknown disables entry of any further details about the recipe:

Selecting Known but checking an Unknown Amount box disables that specific ingredient's amount and unit type inputs (other ingredients may still have known amounts).

Note that you can register materials and mixtures without specifying ingredients or amounts, even when you do not explicitly check one of the 'unknown' boxes. Warning messages are provided to confirm that your registration is intentional.

Once registered, mixtures with unknown ingredients and amounts behave just as any other mixture, with a slight change to their detail view to illustrate unknown amounts or ingredients.

Bulk Registration of Mixtures That Include Unknowns

In bulk registration of Mixtures, some fields support the text "unknown" on import. For details, see Bulk Registration of Entities.

Delete a Mixture

Each Mixture is composed of an entry in the Mixture DataClass table and a Protocol that defines the ingredients used and the steps. To delete the mixture completely, delete the Protocol and then you can delete the Mixture DataClass.

• Switch to the LabKey Server interface via > LabKey Server > [Folder Name]
• Select > Go to Module > Experiment.
• Scroll down to the list of Protocols.
• Select the Protocol(s) to delete, and click to delete.
• You should now be able to delete the Mixture DataClass row.

Use the Recipe API to Update Mixtures

Mixtures can be updated after they are created by using the Recipe API. You can make these updates using PUT requests to recipe-recipe.api:

• Mutation of ingredients and their associated metadata.
• Description can be changed on the underlying protocol.
• Recipe produces metadata.

• Recipe name
• Changing the recipe steps. Use the pre-existing recipe-steps.api endpoint if you're looking to edit these.

The general steps for using the Recipe API are:

1. Call recipe-read.api and receive the full recipe/mixture definition.
2. Mutate the received object in the way you'd like (change ingredients, amounts, etc).
3. 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.
4. Call recipe-recipe.api and PUT the mutated object on the payload as the recipe.

Related Topics

• Managing Ingredients and Raw Materials: Register new ingredients and raw materials
• Registering Batches

• Batch Design
• Batches
• Amounts and Units
• Registering Batches with Unknowns
• Bulk Registration of Batches That Include Unknowns
• Aliquot Batches
• Add Detail to "Raw Materials Used" Dropdown
• Use the Recipe API to Update Batches

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.

Batches

To create a new batch, click Add above the batches grid, or select Manage > 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 or other dropdowns by using Identifying Fields.

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

If you select Known for Materials/Ingredient Source, you can also select whether Amounts/Raw Materials are all Known, or one or more may include Unknown amounts.

To disable all material and amount inputs, click to set 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:

• Aliquot Naming

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 Identifying Fields, administrators can provide their users with the necessary details when they select from the dropdown.

For example, if you define "Product Number" and "Lot Number" as identifying fields, they will appear for users with the "Name" of the raw material.

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

• 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.

The general steps for using the Recipe API for Batches are:

1. Call recipe-getBatch.api and receive the full mixture batch definition.
2. Mutate the received object in the way you'd like (change materials, amounts, etc.).
3. 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.
4. Call recipe-batch.api and PUT the mutated object on the payload as the batch.

Related Topics

• Managing Ingredients and Raw Materials
• Registering Mixtures (Recipes)

Topics on the menu will help Administrators understand and configure the Biologics LIMS application. Learn more here:

• Biologics: Navigate

Biologics Admin Topics

• Biologics: Detail Pages and Entry Forms
• Biologics: Protect Sequence Fields
• Manage Notebook Tags
• Biologics Admin: URL Properties

Related Topics

• Sample Manager Administration
• LIMS: Charts

This topic covers methods for working with data in grids as well as customizing grid views, detail pages, and entry forms in LabKey Biologics LIMS.

• Custom Details Pages
• Entry Forms
• Customize Details Shown for Lookups

• Custom Grid Views
• Scroll Large Grids
• Column Header Menus
• Editable Grids

Custom Details Pages

An administrator can create a special custom grid view to control the fields shown on an entity details page. If you create this special view using the Biologics interface, it will only show for your own user account. To make this change to the details view for all users, select > LabKey Server > [Your Biologics Project Name] to switch to the LabKey Server UI. Here you can save the "BIOLOGICSDETAILS" view and share it with all users.

Customize the view for the entity type, then save it:

• Uncheck "Make default view for all users"/"Default grid view for this page".
• Use the name "BIOLOGICSDETAILS".
• Check the box to "Make this grid view available to all users" (available only in the LabKey Server interface).
• Optionally check the box to "Make this grid view available in child folders."

Entry Forms

To modify entry and update forms, modify the fields in the field designer. For example, to add a field "NIH Registry Number" to the Cell Line entity:

• From the main menu, click Cell Lines.
• Select Manage > Edit Cell Lines Design.
• Click the Fields section to open it.
• Expand the desired field details and enter a Label if you want to show something other than the field name to users.

• Click Finish Editing Source Type.
• The field will appear in the entry form for Cell Lines when you Create a new one.

Follow similar procedures to delete or modify entry form fields for other entities.

Customize Details Shown for Lookups

Lookup fields connect your data by letting a user select from a dropdown which joins in data from another table. By default, a lookup column will only show a single display field from the table, generally the first text field in the target table.

Details for Registry Sources and Sample Types

• Identifying Fields

Details for Lists

You can also customize the lookup view in the Sample Manager, LabKey LIMS, and Biologics LIMS for a list or other table by editing the metadata directly. For example, for dropdown targeting a list of Supplier names, it might also be helpful to users to show the state where that supplier is located. In this example, the "Suppliers" list would include the following XML metadata to set shownInLookupView to true for the desired field(s):

<tables xmlns="http://labkey.org/data/xml">
  <table tableName="Suppliers" tableDbType="NOT_IN_DB">
    <columns>
      <column columnName="State">
        <shownInLookupView>true</shownInLookupView>
      </column>
    </columns>
  </table>
</tables>

Before applying the above, the user would only see the lab name. After adding the above, the user would see both the name and state when using the same dropdown.

Related Topics

• Biologics: Assay Integration
• Create Registry Sources

Protein Sequences and Nucleotide Sequences can be hidden from Biologics users who do not require access to that intellectual property information, while retaining access to other data. This is implemented using the mechanism LabKey uses to protect PHI (protected health information). Sequence fields are marked as "Restricted PHI" by default.

When an administrator configures protection of these fields, all users, including admins themselves, must be explicitly granted "Restricted PHI" access to see the Sequences.

Other fields that contain PHI (protected health information) or IP (intellectual property) can also be marked at the appropriate level, and hidden from users without sufficient permission.

• Restrict Visibility of Nucleotide and Protein Sequences
• PHI/IP Protection Levels and Permissions
• Omit or Blank Protected Columns
• Conditional Viewing of Sequences
• Mark Other Fields as Protected

Restrict Visibility of Nucleotide and Protein Sequences

An administrator can enable Protected Data Settings within the Biologics application. Once enabled, a user (even an administrator) must have the "Restricted PHI Reader" role in the folder to view the protein sequences and nucleotide sequences themselves.

• In the Biologics application, select > Application Settings.
• Scroll down to Protected Data Settings, then check the box to Require 'Restricted PHI' permission to view nucleotide and protein sequences.
• If you don't see this box, you do not have sufficient permissions to make this change.

PHI/IP Protection Levels and Permissions

There are four available 'levels' of protection, detailed in this topic: phiLevels

• Not PHI
• Limited PHI
• Full PHI
• Restricted PHI: the highest level of information to be protected. Sequences are protected at this level.

Omit or Blank Protected Data

You can choose whether to show an empty column (the default) or omit the column entirely.

Learn more in this topic: complianceFolder

Conditional Viewing of Sequences

Once configured as described above, any user without 'Restricted PHI' permission will see that there is a Sequence column, but the heading will be shaded and no sequences shown. Hovering reveals the message "PHI protected data removed"

Users with the 'Restricted PHI' permission role will see the contents of this column.

Mark Other Fields as Protected

Other fields in Registry Source Types and Sample Types may also be protected using the PHI mechanism, when enabled. A user with lower than "Restricted PHI Reader" access will not see protected data. In the LabKey Server interface, they will see a banner to this effect.

The mechanism of setting and user experience is slightly different for Registry Source Types and Samples.

Protect Registry Source Type Fields

When a field in an entity Registry Source Type other than the Sequence fields is set to a higher level of PHI than the user is authorized to access, it will be hidden in the same way as the Sequence fields.

To mark fields in Registry Source Type, such as registry entities including nucleotide and protein sequences, use the LabKey Server interface to edit these "Data Classes".

Protect Sample Fields

When a field in a Sample Type is protected at a higher level of PHI than the user can access, they will not see the empty column as they would for an entity field. To mark fields in Sample Types as PHI/IP, use the Biologics interface.

Related Topics

• phiLevels

In the Biologics LIMS, electronic Lab Notebooks can be organized and color coded using tags, helping users group and prioritize their authoring and review work. New tags can be defined during notebook creation or in advance. You could use tags to represent projects, teams, or any other categorization(s) you would like to use. Each notebook can have a single tag applied.

• Manage Tags
• Delete Unused Tag
• Add New Tag
• Require Tags
• Select Tag for Notebook

Manage Tags

From the main menu, click Notebooks, then select Manage > Tags to open the dashboard.

Tags listed here will be available for users adding new notebooks.

Delete Unused Tag

To delete tags, an administrator can select one or more rows and click Delete. Tags in use for notebooks cannot be deleted.

Add New Tag

To add a new tag, an administrator clicks Create Tag, provides a name and optional description, sets a tag color, then clicks Create Tag again in the popup.

Once added, a tag definition and color assignment cannot be edited.

Require Tags

By default, new notebooks do not require a tag. An administrator can require a tag for every notebook by selecting > Application Settings and scrolling to the Notebook Settings section. Check the box to require a tag.

If this setting is enabled while there are existing notebooks without tags, these notebooks will display a banner message reminding the editor(s) to Add a tag before submitting. Click the to enable the tag selection dropdown.

Select Tag for Notebook

Notebook authors will see the colors and tags available when they create or edit notebooks:

Related Topics

• Notebook Dashboard
• Author a Notebook

The Biologics application offers a number of URL properties that can be used to direct the user to a specific part of the application.

• Last Page You Viewed
• Reports Dashboard
• URL Redirects

Last Page You Viewed

When you are in the LabKey Server interface, you can hand edit the URL to return to the last page you were viewing before switching to LabKey.

Substitute the server and path for your biologics-app.view and append the lastPage property:

https://example.lkpoc.labkey.com/Biologics%20Example/biologics-app.view?#/.lastPage

Reports Dashboard

To view the Reports dashboard, use "/reports":

https://example.lkpoc.labkey.com/Biologics%20Example/biologics-app.view?#/reports

URL Redirects

The following redirects can be done directly to the URL for navigating a user programmatically. Note that these examples assume various rowID to assay mappings that may be different in your implementation.

Related Topics

• urlEncoding