Table of Contents

guest
2022-05-20
LabKey Biologics
   Biologics: Navigate
   Introduction to LabKey Biologics
   Release Notes - Biologics
   Biologics Tutorials
     Biologics Basics: Navigate and Search
     Biologics Tutorial: Add Sequences to the Registry
     Biologics Tutorial: Register Samples
     Biologics Tutorial: Work with Mixtures and Batches
     Biologics Tutorial: Create a New Biologics Project
     Customizing Biologics: Purification Systems
   Biologics: Terminology
   Biologics: Projects and Folders
   Biologics: Bioregistry
     Biologics: Search Options
     Create and Edit Entities
       Register Nucleotide Sequences
       Register Protein Sequences
       Register Leaders, Linkers, and Tags
       Register Molecules
     Protein Sequence Annotations
     CoreAb Sequence Classification
     Molecule Sets and Molecular Species
     Vectors, Constructs, Cell Lines, and Expression Systems
     Entity Lineage
     Customize the Bioregistry
     Bulk Registration of Entities
     Use the Registry API
   Biologics: Samples
     Biologics: Create Samples
     Biologics: Manage Samples
     Sample Comparison Report
   Biologics: Assay Data
     Biologics: Upload Assay Data
     Biologics: Work with Assay Data
   Biologics: Media Registration
     Registering Ingredients and Raw Materials
     Registering Mixtures (Recipes)
     Registering Batches
   Biologics: Workflow
     Biologics: Create Workflow Job
     Biologics: Process Parameters
   Biologics: Electronic Lab Notebooks
     Notebook Dashboard
     Create a Notebook
     Manage Projects
     Notebook Review
     Notebook Templates
     Configure Puppeteer
     ELN: Frequently Asked Questions
   Biologics: Freezer Management
     Biologics: Shared Freezers
   Biologics Administration
     Biologics Admin: Grids, Detail Pages, and Entry Forms
     Biologics: Protect Sequence Fields
     Biologics Admin: Charts and Reports
     Biologics Admin: Set Up Assays
     Biologics Admin: Assay Integration
     Biologics Admin: Building from Source
     Biologics Admin: URL Properties
   LabKey Biologics - Videos

LabKey Biologics


LabKey Biologics is designed to enable biopharma and bioprocessing research teams to manage and interlink samples, data, entities, workflows, and electronic laboratory notebooks.

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 using a digital match for your physical storage.
To learn more, register for a product tour, or request a customized demo, please visit our website here:

Biologics Release Notes

Biologics Trial Server and Tutorials

Biologics Overview

Bioregistry

Samples for Biologics

Assay Management

Media Registration

Workflow

ELN

Freezer Management

Related Topics




Biologics: Navigate


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:

On the dashboard, you'll see panels displaying:

  • Dashboard Insights: A selectable set of visualizations, defaulting to the Sample Count by Status.
  • Jobs List: The home for workflow jobs. If any tasks were assigned to you, they would be shown on Your Queue and can be filtered by priority.
  • Freezer List: At a glance storage details and access to your virtual freezers.

In-App Notifications for Background Imports

When assay or sample data import by file or copy/paste is large enough that it will take considerable time to complete, the import will automatically be done in the background. Files larger than 100kb (or a copy/paste of > 1000 rows) will be imported asynchronously. This allows users to continue working within the app while the import completes. To see all such imports currently underway, select Background Imports from the user/avatar menu.

In the header, the Notifications menu will report when background imports are completed. While an import is underway, the bell icon will be replaced with a spinner icon. The number superimposed on the menu indicates how many notifications are available.

The spinner icon will also be shown to users viewing the Sample Type or Assay currently being imported in the background making it clear that the data is in an incomplete state.

Learn more about asynchronous background imports in the companion topic for Sample Manager.

Navigation

The main Menu is available throughout the application and gives you quick access to all aspects of Biologics

Click the menu categories (in blue) for sub-dashboards, such as for the Registry or all Assays. Click individual menu items for that specific category.

The home pages for entities provide links to other entity home pages, here viewing "Molecules". Click a different entity type to switch your view. Use the and icons to scroll in narrower browsers.

Detail pages for some kinds of entities, such as protein and nucleotide sequences, include multiple tabs, such as Lineage and Sequence, shown here.

Registry

The Registry dashboard shows all of the unique entities that have been added, such as Molecules, Expression Systems, Cell Lines, etc. Click a tile or select a category from the main menu to learn more or register new entities:

Click See Entity Relationships to see the various entities and relationships recognized by the registry. Learn more in this topic: Biologics: Terminology.

Each entity in the registry has a details page which includes basic properties of the entity, and a list of related entities.

Sample Types

The Sample Types dashboard shows a grid of sample types defined in the system.

If you switch the Grid to the Heatmap view, you'll see a visualization of samples recently added to the registry. Rows represent sample types and columns represent months. Darker panels indicate more samples for that month/sample type combination.

Learn more in the topic: Biologics: Manage Samples.

Assays

The Assays dashboard shows the assays defined in your system. Similar to the Samples dashboard, a heatmap is also available.

Learn more in the topic: Biologics: Assay Data

Storage

Managing contents of your freezers by creating an exact virtual match of your physical storage system, and then track where each sample can be found.

Learn more about creating, customizing, and using freezers in the Sample Manager documentation here:

Workflow

The Workflow dashboard shows a Job List (or heatmap) of active workflow jobs and tasks in the system.

The tabs each show the count of jobs in the different categories:

  • Your Queue: Jobs and tasks assigned to you.
  • All Active Jobs: Jobs that have not been completed, including but not limited to the ones in your own queue.
  • Completed Jobs: Jobs that have been completed.
  • All Jobs: All of the above.
  • Job Templates: See all the active templates.
Learn more in the topic: Biologics: Workflow

Media

From the Media dashboard, you add and manage ingredients, raw materials, mixtures, and batches.

Learn more in the topic: Registering Ingredients and Raw Materials

Notebooks

Collaborate and record your work in data-connected Electronic Lab Notebooks. Use templates to create many similar notebooks, and manage individual notebooks through a review and signing process.

Learn more in this section:

Related Topics

Learn more about each aspect of the registry in these detailed topics:




Introduction to LabKey Biologics


LabKey Biologics aims to speed the discovery of biologic therapies by providing key tools for research teams, including:

  • A consolidated knowledge base to store and organize everything you need to make scientific decisions
  • Efficient and reproducible capture and integration of your data, from samples, assays, and experiments
  • Tools promoting collaboration among teams for smooth handoffs and reproducible procedures
  • Media management for clear tracking of ingredients and mixtures.
  • A data-integrated electronic lab notebook (ELN)
  • Freezer management aligning your physical storage with digital storage and tracking.
This topic provides an introductory tour of these key features.

Knowledge Base

Bioregistry

The Bioregistry forms the team's shared knowledge base, containing detailed information on your sequences, cell lines, expression systems, and other research assets. The Bioregistry recognizes nine entity types:

  • Cell Lines
  • Constructs
  • Expression System
  • Molecules
  • Molecule Sets
  • Molecule Species
  • Nucleotide Sequences
  • Protein Sequences
  • Vectors
If desired, these entity types are customizable to reflect the focus of your research project or simply to suit the terminology preferred by your organization.

Data Grids

Each entity type is organized into data grids that can be filtered, sorted, and searched to find items of interest. A search bar above each data grid provides intuitive querying for entities. Data grids are customizable to show those columns that are most relevant to the research effort.

Entity Details

Click an entity in a grid to see its details page. Each details page shows the entity's properties and relationships to other entities. All details pages can be configured to show the most relevant data. For example, the details page for a protein sequence shows the chain format, average mass, extinction coefficient, the number of S-S bonds, etc., while the details page for a expression system shows the cell lines, constructs, and target molecule, as well as the samples drawn from it.

Entity Relationships

Each details page contains a panel of relationships to other entities. For example, for a given protein sequence, the relationship panel shows:

  • which expression systems it is included in
  • which molecules it is a part of
  • which nucleotide sequence encodes for it
Entity relationships are shown as links to other details pages, making it easy to follow lineage lines and to track down associated samples and experimental data.

To get a sense of how the Registry knowledge base stores entities and their relationships, follow the tour steps below on your Biologics Trial Server. You should have another browser window open on the home page of your trial.

This series of clicks navigates through entities related to a particular protein sequence (the Nivolumab Light Chain).
  • Navigate to the Biologics home page.
  • Click the Menu.
  • Under Registry, click Protein Sequences.
  • In the data grid, click PS-24. Notice the detailed information about the Nivolumab Light Chain protein sequence.
  • Scroll down to the Related Entities panel and click M-3. Notice the detailed information about the Nivolumab molecule.
  • Scroll down to the Related Entities panel and click ES-3. This expression system is linked to assay result data, as shown below.

Capture and Integration

Data about your samples, experiments, and instrument assay results can be integrated to provide a full data landscape. Design customized methods for representing and linking your information.

Inventory

Samples, media stocks, and other lab assets are stored in an inventory, organized into data grids and detail pages, similar to the way entities are stored in the Registry. Names for newly created samples are generated according to a pre-defined pattern controlled by administrators. Sample names can be built up from elements such as dates, incrementing numbers, static text, project names, etc. For example:

  • vial-0001
  • S-11.22.2019-0001
  • BarCode-20191122.0001
Existing sample inventories can be easily imported into the system.

Sample Lineage

The inventory system also understands sample vial relationships and lineage, that is, parent and child vials. A graphical view shows the upstream and downstream lineage of the current sample. The same information is also available in a grid form, which allows you to navigate via the parentage lines to related sample vials.

Media Recipes and Batches

The inventory also lets you define both media recipes and real batches of media, so you can track current state of your lab stocks.

To get a sense of how experiments link together samples and result data, follow the tour steps below on your biologics trial server. This series of clicks navigates from assay result data (for Cell Viability) to related sample information and lineage.
  • Click the Menu in the header.
  • Under Assays, click Cell Viability.
  • Click the Results sub-tab. This data grid shows all of the Cell Viability data in the registry.
  • Click the sample S-001. This sample was used to generate one row of the Cell Viability data.
  • Click the Lineage sub-tab. Notice the graph showing the parent expression system from which the sample was drawn.

Analytics and Visualizations

Analytics and visualizations can be included throughout LabKey Biologics to provide key insights into the large molecule research process.

Protein Classification Engine

When new protein sequences are added to the Registry, they are passed to the classification and annotation engine, which calculates their properties and identifies key regions on the protein chain, such as leader sequences, variable regions, and constant regions. (Researchers can always override the results of the classification engine, if desired.) Results are displayed on the Sequence tab of the protein's detail page. Identified regions are displayed as multicolored bars, which, when clicked, highlight the annotation details in the scrollable section below the sequence display.

On your biologics trial server, you can reach this same sequence:
  • Click the Menu in the header.
  • Under Registry, click Protein Sequences.
  • In the data grid, click PS-24.
  • Click the sub-tab Sequence. Notice the sequence analysis panel which displays multi-colored sub-sequences and associated annotations.

Collaboration Among Teams

A fully customizable task-based workflow system is included in LabKey Biologics. Individual users can all be working from the same knowledge base with personalized task queues and priorities. While no example tasks or templates are included with your trial, you can create your own.

  • Click the Menu in the header.
  • Click Workflow.
  • Click Create.
  • Under Workflow, you have two options:
    • Job: Design a job with subtasks, assignments, connections to entities and samples, etc.
    • Job Template: Design a template for creating many similar jobs.

Media Management

In the Media section of the main menu, you will find sections for tracking:

  • Batches
  • Ingredients
  • Mixtures
  • Raw Materials
Careful tracking of media and components will help your team develop quality production methods that are reproducible and scalable.

Electronic Lab Notebook

Our data-integrated ELN (electronic lab notebook) helps you record results and support collaboration and publication of your research. Directly link to relevant registry entities, specific result runs, and other elements of your biologics research. Submit for review and track feedback and responses within the same application.

Learn more in this section:

Freezer Management

When you use Freezer Management tools within LabKey Biologics, you can directly track the locations of samples and media in all the freezers your team uses. Create an exact digital match of your physical storage and record storage details and movements accurately. Sample data is stored independently of storage data, so that all data is retained even after a sample is consumed or removed from storage.

Learn more in the Sample Manager documentation here:




Release Notes - Biologics


LabKey's Biologics LIMS is designed to help teams efficiently manage Laboratory workflows and data for large molecule research and development.

This topic details changes and enhancements in each release as a guide to help users track changes. Application-specific changes are listed by monthly version, along with a link to the general release notes for each major LabKey Server release.

Release 22.5, May 2022

  • Updated grid menus: Sample grids now help you work smarter (not harder) by highlighting actions you can perform on samples and grouping them to make them easier to discover and use.
  • Revamped grid filtering interface and column header menus replace the "omnibox" for more intuitive sorting, searching and filtering.
  • Sort and filter based on 'lineage metadata', bringing ancestor information (Source and Parent details) into sample grids.
  • Rename Data Classes and Sample Types to support flexibility as your needs evolve. Names/SampleIDs of existing samples and bioregistry entities will not be changed.
  • Export a signed and human readable ELN snapshot, reliably recording your work.

Release 22.4, April 2022

  • Download templates from more places, making file imports easier. (docs)
  • Share freezers across multiple Biologics subfolders. (docs)
  • Manage user accounts and permissions assignments within the Biologics application. (docs)
  • Full text search will find results across Bioregistry entities, samples, notebooks, and more. (docs)
  • Use the Sample Finder to find samples based on parent properties, giving users the flexibility to locate samples based on bioregistry details and lineage details. (docs)

Release 22.3, March 2022

  • Notebook Entry Locking and Protection: Users are notified if someone else is already editing a notebook entry and prevented from accidentally overwriting their work. (docs)
  • Copy and paste from Google Sheets or Excel to add a table to a notebook. (docs)
  • Redesigned main dashboard featuring storage information. (docs)
  • Updated freezer overview panel and dashboards present storage summary details. (docs)
  • Available freezer capacity is shown when navigating freezer hierarchies to store, move, and manage samples. (docs | docs)
  • Storage labels and descriptions give users more ways to identify their samples and storage units. (docs)

Release 22.2, February 2022

  • Find notebooks easily based on a variety of filtering criteria. See your own ELN task status(es) at a glance. (docs)
  • Users will see progress feedback for background imports being processed asynchronously. (docs)
  • New Storage Editor and Storage Designer roles, allowing admins to assign different users the ability to manage freezer storage and manage sample and assay definitions. (docs)
    • Note that users with the "Administrator" and "Editor" role no longer have the ability to edit storage information unless they are granted these new storage roles.
  • Sample Type Insights panel summarizes storage, status, etc. for all samples of a type. (docs)
  • Sample Status options are shown in a hover legend for easy reference. (docs)
  • When a sample is marked as "Consumed", the user will be prompted to also change it's storage status to "Discarded" (and vice versa). (docs | docs)
  • User-defined barcodes in integer fields can also be included in sample definitions and search-by-barcode results. (docs)
  • Search menu includes quick links to search by barcode or sample ID. (docs)

Release 22.1, January 2022

  • ELN improvements:
    • Tables pasted into an ELN will be reformatted to fit the page width. Users can adjust the display before exporting or finalizing the notebook. (docs)
    • Printing to PDF includes formatting settings including portrait/landscape and fit-to-page. (docs)
    • Comments on Notebooks will send email notifications to collaborators with more detail. (docs)
  • A new Text Choice data type lets admins define a set of expected text values for a field. (docs)
  • Naming patterns will be validated during sample type definition. (docs)
  • User-defined barcodes can be included in Sample Type definitions as text fields and are scanned when searching samples by barcode. (docs | docs)
  • Editable grids include visual indication when a field offers dropdown choices. (docs)
  • Add freezer storage units in bulk (docs)
  • If any entities are named using only digits as names, these could create ambiguities if overlapped with the "rowIDs" of other entities, producing unintended results or lineages. With this release, such ambiguities will be resolved by assuming a name has been provided. (docs)

Release 21.12, December 2021

  • Freezer Management for Biologics: Create a virtual match of your physical storage system, and then track sample locations, availability, freezer capacities, and more. (docs)
  • Samples can be gathered on user-curated picklists to assist in many bulk actions. (docs)
  • Workflow job sample lists, and other grid views containing samples of different types, offer tabs for viewing all the samples of each individual type as well as a consolidated tab showing all samples. (docs)
  • When a workflow job includes samples, tasks that import assay data will auto-populate the assigned samples. (docs)
  • Additional formatting options available for electronic lab notebooks, including special characters. (docs)

Release 21.11, November 2021

  • Manage process parameters in lab workflows. Available in development mode. (docs)
  • Archive an assay design so that new data is disallowed, but historic data can be viewed. (docs)
  • Manage sample statuses like available, consumed, and locked. (docs)
  • Incorporate lineage lookups into sample naming patterns. (docs)
  • Apply a container specific prefix to all bioregistry entity and sample naming patterns. (docs)
  • Prevent users from creating their own IDs/Names in order to maintain consistency using defined naming patterns. (docs)
  • Release Notes 21.11 (November 2021)

Release 21.10, October 2021

  • Customize the definitions of data classes (both bioregistry and media types) within the application. (docs)
  • Sample detail pages include information about aliquots and jobs. (docs)
  • Customize the naming pattern used when creating aliquots. (docs)
  • Comments on workflow job tasks can be formatted in markdown and multithreaded. (docs)
  • Redesigned job tasks page (docs)

Release 21.9, September 2021

  • Edit lineage of selected samples in bulk (docs)
  • Customize the names of entities in the bioregistry (docs)
  • Redesigned job overview page (docs)
  • Lineage graphs changed to show up to 5 generations instead of 3 (docs)

Release 21.8, August 2021

  • Aliquot views available at the parent sample level. See aggregate volume and count of aliquots and sub-aliquots. (docs)
  • Find samples using barcodes or sample IDs (docs)
  • Import aliases for sample parents are shown in the Sample Type and included in downloaded templates. (docs)
  • Improved options for managing workflow and templates (docs)

Release 21.7, July 2021

  • Electronic Lab Notebooks are available as an integrated part of the Biologics application. (docs)
    • Data-connected ELN connects your analysis directly to the supporting work
    • Collaboratively author, review, and discuss notebook entries and data
    • Add context and clarity to your work, accelerating the review and publication process.
  • Removal of the previous "Experiment" mechanism. Use workflow jobs instead.
  • A new Job Builder interface makes creating workflow jobs easier. (docs)
  • Release Notes 21.7 (July 2021)

Release 21.6, June 2021

  • Create and manage Aliquots of samples (docs)
  • Parent details are included on the Overview tab for samples (docs)

Release 21.5, May 2021

  • Nucleotide and Protein Sequence values can be hidden from users who have access to read other data in the system. (docs)
  • Sample Types and Data Classes can include:
    • Marking of fields at different levels of PHI. (docs)
    • Fields to reference files and attachments. Learn more in the Sample Manager documentation here. (docs)

Release 21.4, April 2021

  • Generate barcodes for Samples with "UniqueID" field type (docs)
  • Options to create samples from more places in the application (docs)
  • Create pooled samples and/or derive new samples from one or more parents (docs)
  • Integrated workflow with job templates and personalized queues of tasks (docs)
  • Specialty Assays can now be defined and integrated, in addition to Standard Assays (docs)
  • Creation of Raw Materials in the application uses a consistent interface with other sample type creation (docs)
  • When inferring fields to define data structures, the "reserved" fields will not be shown, but are always created (docs)
  • When importing data, any unrecognized fields will be ignored; in some cases a banner will be shown (docs)

Release 21.3, March 2021

  • User experience improvements include:
    • A new home page, which highlights samples and recently added assay data. (docs)
    • A new navigation menu, conveniently available throughout the application. (docs)
  • Sample Types and Assay Designs can now be created and managed with a Biologics-based user interface. (docs | docs)
  • In-app Notifications are provided when background imports are completed. (docs)
  • Release Notes 21.3 (March 2021)

Release 20.11, November 2020

  • Sample Management - Improved user experience for defining and importing samples, and generating sample IDs, including importing samples by drag-and-drop and directly entering sample information in the user interface. (docs)
  • Assay Data Management - Improved user experience for defining, importing and managing assay data directly in the Biologics application. (docs)
  • Sequence Validation - Improved validation of whitespaces and stop codons in nucleotide and protein sequences. (docs)
  • Release Notes 20.11 (November 2020)

Release 20.7, July 2020

  • Sample Import - Expanded sample import options within the Biologics application. (docs)
  • Assay Data Import and Re-import - Improved interface for importing and re-importing assay data. (docs)
  • Release Notes 20.7

Release 20.3, March 2020

  • Sample Comparison Reports - Create assay summary reports for selected samples. (docs)
  • Improved Data Grid Paging - Improvements allow you to select the number of rows to show on a given page and to jump to the first or last page directly. (docs)
  • Release Notes 20.3

Release 19.3, November 2019

  • Lineage Improvements - The Lineage tab provides graphical and grid views on lineage relationships, as well as sample details. (docs)
  • Reports tab - The Reports tab displays custom grids and charts added by administrators. (docs)
  • Release Notes 19.3

Release 19.2, July 2019

  • Expanded Characters in Sequences. DNA/RNA sequences can use expanded characters beyond A, C, G, T, and U. (docs)
  • Reporting Enhancements User-created reports, charts, and custom grids are collected and displayed on the Reports tab. (docs)
  • Assay QC States - Configure and use custom states for quality control workflows in assays. Available in both LabKey Server and Biologics. (admin docs) and (Biologics user docs)
  • Release Notes: 19.2

Release 19.1, March 2019

  • Custom Charts and Grids - Display charts and custom grids within Biologics. (docs)
  • File Attachments - Attach files to experiments. (docs)
  • Bulk Upload Ingredients and Raw Materials - Import ingredients and materials in bulk using Excel, TSV, and other tabular file formats. (docs)
  • Support for 'Unknown' Ingredients - Include "unknowns" in bulk registration of mixtures and batches. (docs)
  • Improved Batch Creation - Add an ingredient off recipe during the creation of a batch. (docs)
  • Assay Data for Samples - When a sample has multiple associated assays, the results are displayed on different tabs on the sample's details page. (docs)
  • Release Notes 19.1

Release 18.3, November 2018

  • Biologics Trial Servers Available - Create a web-based server instance to explore LabKey Biologics. (docs)
  • Experiment Framework - Manage experiments, associated samples and assay data. Add and remove samples from an existing experiment. View the assay data linked to samples in an experiment. (docs)
  • Lineage Grid - View sample lineage in a grid format. (docs)
  • Import Constructs from GenBank Files - Import Constructs using the GenBank file format (.gb, .genbank). (docs)
  • Custom Views - Administrators can define and expose multiple views on Biologics grid data, allowing end users to select from the list of views. (docs)
  • Tutorials - Use these tutorials as a guided tour of LabKey Biologics:
  • Release Notes 18.3

Release 18.2, July 2018

  • Experiments - Build and define experiments with samples. (docs)
  • Details for Related Entities - The user interface for related entities has been improved with expandable details panels. (docs)
  • Editable Grid Improvements - Insert sample details or upload assay data in a grid. (docs)
  • Bulk Import for Media - Quickly specify ingredients for recipes or batches. (docs)
  • Release Notes 18.2

Release 18.1, March 2018

  • Improved Navigation - Redesigned navigation bars have replaced the "breadcrumb" links. Multiple tabs have been added to select details pages in the registry. (docs)
  • Bulk Import Entities - Bulk import nucleotide sequences, protein sequences, molecules, mixtures, and mixture batches using an Excel file, or other tabular file format. (docs)
  • Editable Grid for Assay Data - Enter assay data directly into the data grid without the need for a file-based import. (docs)
  • GenBank File Format - Import and export data using the GenBank file format. (docs)
  • Multiple Sample Assay Data Upload (docs)
  • Improved Media Registration - Include an expiration date for batches of media. Mark raw materials and media batches as "consumed" to track the current supply. (docs)
  • Release Notes 18.1

Release 17.3, November 2017

Release 17.2, July 2017

  • Vendor Supplied Mixtures - Add vendor supplied materials and mixtures to the registry, even when exact ingredients and/or amounts are unknown.
  • Editable Registry Fields - Some fields in the registry can be directly edited by the user, such as description and flag fields.
  • Media Batches - Users can create media batches using recipes and ingredients already entered into the repository.
  • Improved Sample Creation - A new sample generation wizard makes it easier to enter new samples in the repository, and to link them with existing DataClasses and parent samples.
  • Release Notes 17.2

March 2017

  • LabKey Biologics is Launched!



Biologics Tutorials





Biologics Basics: Navigate and Search


This topic provides a guided tour of LabKey Biologics' user interface and search functionality, including:

Set Up Trial Server

  • To follow this topic as a tutorial and see the same entries, you can register and create a Biologics Trial instance.
  • If you have already created a biologics trial server, select it, and login: Your Sites
  • On your site, click Explore.
You can also follow these steps on your own server, though search results and browsing will differ.

Main Dashboard and Menus

This section provides a quick tour of LabKey Biologics. Click along as directed to see different aspects of the data and the available tools.

Biologics Home Page

  • Navigate to your Biologics home page.
  • 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 additional menus in the upper right:

On the dashboard, you'll also see panels displaying:

  • Dashboard Insights: A selectable set of visualizations, defaulting to the Sample Count by Status.
  • Jobs List: The home for workflow jobs. If any tasks were assigned to you, they would be shown on Your Queue and can be filtered by priority.
  • Freezer List: At a glance storage details and access to your virtual freezers.

Bioregistry

In the main header Menu, click Registry.

The Registry section is where you will find all the different Entities in the system: Molecule Sets, Molecules, etc.

Data Grids

  • Click Molecules.
The Molecules page shows a data grid of all of the registered Molecules.

Detail Pages

  • Click M-3.
  • The M-3 Details page shows properties, components, related entities of this molecule.
  • Scroll down to view the related entities.
  • Return to the Molecules grid page by clicking Molecules in the submenu bar. You can also use the main menu.

Search Biologics

Learn more about search in this topic:

The following browsing path will help you explore some linkages in our trial sample data.
  • In the header search panel, enter:
    IgG1
  • While there are only a few results, explore filtering them:
    • Click Advanced
    • Open the dropdown menu and select Molecule.
    • Click Search.
  • Click the M-1 search result.
  • Scroll to the Molecule Components and click PS-17.
    • If you click anywhere in the bar, the section will expand. Click the actual name link "PS-17" to switch to that entity's details.
  • Click Sequence. The Sequence tab shows sequence annotations (the results of the sequence analysis engine).
  • Click Protein Sequences.
  • You are taken to a data grid of the registered protein sequences.
  • Clicking in the "Select..." omnibox above any grid brings up a dropdown of options: filter, keyword search, sorting, and selecting grid views by name (when any are defined).
  • If you type directly into the box, you will search. Enter the following text in the search bar:
    IgG4
  • The search returns a few results.
  • Sort by clicking the menu icon in the column header Avg. Mass and selecting Sort ascending.
  • Modifications of the grid accumulate in the search bar in lozenge boxes.
  • Clear the modifications to return the grid to its original state. To reveal the 'X' for deleting, hover over the lozenge.

The guided tour continues in the following topic: Biologics Tutorial: Add Sequences to the Registry

Next Tutorial

Biologics Tutorial: Add Sequences to the Registry




Biologics Tutorial: Add Sequences to the Registry


This tutorial provides step-by-step instructions for adding an antibody, Aducanumab, to the Biologics registry.

Along the way it illustrates:

  • Adding nucleotide sequences to the registry
  • Options for translating protein sequences from the above
  • Entity relationships
  • The protein classification system which detects and annotates protein formats and components
  • Calculated values for new sequences
This topic describes the manual process for adding single entities to the registry in the UI. There are other options for adding entities, including bulk import options, importing GenBank files, and API-based insert methods.

Note that when you create your own entities, the registry names are auto-generated, and therefore may differ from the names shown in these tutorials.

Set Up Trial Server

  • This tutorial assumes that you have registered and created a Biologics Trial instance of the server.
  • If you have already created a biologics trial server, select it, and login: Your Sites

Register a Nucleotide Sequence

We register a sequence composed of a leader sequence + the light chain for Aducanumab.

  • In the header, click the main Menu.
  • Under Registry, click Nucleotide Sequences.
  • On the Nucleotide Sequences page, click Create and select Nucleotide Sequence.
  • On the page Register a New Nucleotide Sequence, fill out the form as follows:
  • Name: Leave this blank for the tutorial.
  • Description: Copy and paste this text:
Signal Peptide 4 + Aducanumab Light Chain. The Light chain sequence of a IgG1 monoclonal antibody, which targets aggregated forms of β-amyloid (Aβ) in the hopes of reducing its buildup. Leader sequence HV103_HUMAN has been added.
  • Alias: Add the two values below. Hit the Tab key to confirm each entry:
Aducanumab Light Chain

HV103_HUMAN
  • Nucleotide Sequence Parents: Leave Blank
  • Sequence: Copy and paste this sequence:
ATGGACTGGACCTGGAGGATCCTCTTCTTGGTGGCAGCAGCAACAGGTGCCCACTCGGATATTCAGATGACCCAGAGCCCGAGCAGCCTGAGCGCGAGCGTGGGCGATCGCGTGACCATTACCTGCCGCGCGAGCCAGAGCATTAGCAGCTATCTGAACTGGTATCAGCAGAAACCGGGCAAAGCGCCGAAACTGCTGATTTATGCGGCGAGCAGCCTGCAGAGCGGCGTGCCGAGCCGCTTTAGCGGCAGCGGCAGCGGCACCGATTTTACCCTGACCATTAGCAGCCTGCAGCCGGAAGATTTTGCGACCTATTATTGCCAGCAGAGCTATAGCACCCCGCTGACCTTTGGCGGCGGCACCAAAGTGGAAATTAAACGCACCGTGGCGGCGCCGAGCGTGTTTATTTTTCCGCCGAGCGATGAACAGCTGAAAAGCGGCACCGCGAGCGTGGTGTGCCTGCTGAACAACTTTTATCCGCGCGAAGCGAAAGTGCAGTGGAAAGTGGATAACGCGCTGCAGAGCGGCAACAGCCAGGAAAGCGTGACCGAACAGGATAGCAAAGATAGCACCTATAGCCTGAGCAGCACCCTGACCCTGAGCAAAGCGGATTATGAAAAACATAAAGTGTATGCGTGCGAAGTGACCCATCAGGGCCTGAGCAGCCCGGTGACCAAAAGCTTTAACCGCGGCGAATGC
  • Annotations: Leave Blank
  • On the bottom right of the page, click Next.
  • On the Confirm tab, review your entries and click Finish.
    • Notice you could also translate a protein sequence immediately but to illustrate the two processes separately, just click Finish for now.
  • The registry nucleotide sequence will be added to the registry. The name of the sequence (in these screenshots "NS-13") may be different in your registry, as we had the name generated automatically. Once a new sequence is added, the registry enforces its uniqueness: if you attempt to register the same sequence twice, you will receive an error message.

Note that you can protect the visibility of both Nucleotide and Protein Sequences in Biologics so that only specific users will ever see the actual sequence itself, while more users have access to the metadata about the sequence. Learn more in this topic:

Translate and Register a Protein Sequence

To translate a protein sequence based on this nucleotide sequence, follow the instructions below.

  • On the Nucleotide Sequences page, click NS-13, or whatever the system has named your new nucleotide sequence.
  • On the nucleotide sequence details page, select Create > Protein Sequences. (Note there are similar workflows available for Constructs and Vectors.)

  • On the page Register a New Protein Sequence, enter the following information in the form:
  • Name: Leave this blank for the tutorial.
  • Description: Leave the automatically entered text unchanged.
  • Alias:
Aducanumab Light Chain
  • Organisms:
Human
  • Protein Sequence Parents: Leave blank. (Use this when parent protein sequences are already in the registry.)
  • Seq Part: Leave blank. (Use this when you know the sequence type, like Leader, Linker, or Tag.)
  • Click Next.
  • On the Sequence tab, click the dropdown Translation Frame and select "1". (Note that selecting "2" or "3" will re-render the sequence preview panes, as will manually refining the Protein Start and End points.)
  • Click Next.
  • The system searches the protein classification library and generates annotations for the sequence parts.
  • Click Next on all remaining screens of the wizard. The wizard shows you calculated information on the following tabs:
  • On the Annotations tab, review the information, and click Next.
  • On the Properties tab, the system calculates a number of physical properties of the protein sequence. Review the information, and click Next.
  • On the Confirm tab, click Finish.
  • The new protein will be added to the registry. The auto-generated name of the new protein (in this case PS-27) may be different in your registry.
  • Click the name of the new protein to see the details page. Under Related Entities, notice the link to the originating nucleotide sequence (NS-13).

Related Topics

Tutorial Curriculum

Biologics Basics: Navigate and Search

Biologics Tutorial: Register Samples




Biologics Tutorial: Register Samples


This tutorial shows you how to work with samples in LabKey Biologics, showing you how to:
  • Register new samples
  • Generate Sample IDs
  • Link the samples to assay result data

Register Samples

In this step we register new samples in the system, along with generated sample ids.

  • On the main menu, click Sample Types.

In the grid, click Samples to open the Sample Type named "Samples".

On the next page, select Create > Samples to create new samples of this type. Note that we are using a sample type named "Samples" for this example. Directly below that option, you can use a dropdown menu (also labelled "Samples") to select another sample type if desired.

In the sample registration form:

  • Notice that the Sample Type is already set to "Samples".
  • Notice that the Create Samples from Grid tab is preselected. The option to import sample data from a file is also supported.
  • Click Bulk Insert.
  • In the popup:
    • Enter 5 in the New Samples box.
    • Description: For Glucose runs
    • Sample Kind: broth draw
    • Click Add Samples to Grid.
  • Notice that the Sample ID will be generated for you and the Description and Sample Type columns have the shared values you entered.
  • Click Finish creating 5 Samples.

5 samples are registered. Their Sample IDs are generated using the pattern (visible in the sample overview):

S-${sampleDate:date('yy')}${sampleDate:yearlySampleCount:number('0000')}

Which means "S-" followed by a two digit year based on the value you provide for sampleDate, followed by a four digit yearly sample counter. Since our example did not enter a date value, it will create sample ids like:

S-0001
S-0002
S-0003

The actual sample ids that are generated may be different for you, depending on the current state of your sample registry. Administrators have complete control over the sample naming pattern to suit the needs of your organization.

Upload Experiment Results ("Assay" Data)

In this step we upload assay data for our new samples.

  • Use the checkbox at the top of the column to select all five samples.
  • Select Create > Assay Data > Glucose.
  • Enter the following data:
    • Operator: your name
    • Assay Id: enter a name for the assay run, like "Run1"
    • Comments: "Routine glucose checks."
    • Assay Request: leave blank, as there is no pre-existing assay request to fulfill. If there was such a request, you could select it here to track its status.
    • Results: Enter the data below, either manually using Enter Data into a Grid or by Copy-and-paste Data (include the header row when you copy and paste).
    • NOTE: If the Sample IDs generated for you are different, modify this table before you import it. Otherwise your results will not be linked with the samples you created.
SampleIdCultureDayGlucose
S-01611100
S-0160290
S-0159380
S-01587100
S-015714100
    • Click Save and Finish.
  • You are taken to the details page for this run.
  • Click Batches to see all of the Glucose data so far registered. Your latest entry appears as the last item in the grid.
  • Click the Runs sub-tab to see all run-level data.
  • Click the Results sub-tab to see all glucose result data. You may need to tab to the next page or sort/filter the data to see the specific result rows you just entered.

Tutorial Curriculum

Biologics Tutorial: Add Sequences to the Registry

Biologics Tutorial: Work with Mixtures and Batches




Biologics Tutorial: Work with Mixtures and Batches


This tutorial works with media and media recipes. The tutorial shows you how to:
  • Register a new media mixture. In the Biologics terminology, a "mixture" is a recipe, i.e., instructions for mixing together ingredients. A mixture is a virtual entity, not a physical thing that you can place in a bottle.
  • Register a physical batch of the mixture. In the Biologics terminology, a "batch" is a physical thing, i.e., the physical result of following the instructions in a recipe/mixture.

Register a Mixture

Mixtures are designed to register lab recipes and formulations. Their components are ingredients and protocol descriptions.

  • From the main menu, under Media, click Mixtures.
  • Select Create > Mixture.
  • On the Details tab, enter the following:
    • Mixture Name: PBS - Cold Spring
    • Description: Cold Spring formulation with optional ingredients.
    • Alias: cold spring
    • Mixture Type: Solution
    • Click Next.
  • On the Ingredients tab, enter the following:
    • Recipe Measure Type: Volume
    • Expiration Time: 90 Days
    • Ingredients: Known
    • Click Bulk Upload.
    • In the pop-up dialog, copy-and-paste the following recipe into the text box.
TypeIngredient/MixtureAmountUnit Type
IngredientSodium Chloride80g/L
IngredientPotassium Chloride2g/L
IngredientSodium Phosphate Dibasic Anhydrous14.4g/L
IngredientPotassium Phosphate Monobasic2.4g/L
IngredientCalcium Chloride, Dihydrate, Granular1.33g/L
IngredientMagnesium chloride Anhydrous1g/L
    • Click Add Ingredients to submit the recipe.
    • Click Next.
  • On the Preparation tab:
    • Click Add Step.
    • In Step Description enter the following:
      Dissolve the reagents in 800 mL of H2O. Adjust the pH to 7.4 (or 7.2, if required) with HCl, and then add H2O to 1 L. Dispense the solution into aliquots and sterilize them by autoclaving for 20 min at 15 psi (1.05 kg/cm2) on liquid cycle or by filter sterilization. Store PBS at room temperature.
    • Click Next.
  • On the Confirm tab:
    • Review the entries and click Finish.

Create a Batch

  • Select Create > Media > Batch.
  • On the Details tab, enter the following:
    • Mixture Used: PBS - Cold Spring
    • Batch Name: Enter "Batch for Project H", or leave this field blank and Biologics will generate a batch name for you.
    • Alias: Leave blank.
    • Description: Enter "Progress evaluation of Project H"
    • Vendor/Part No. : Leave blank.
    • Consumed: Leave unchecked.
    • Click Next.
  • On the Preparation tab, enter the following:
    • Desired Batch Yield: 1
    • Use the dropdown to select: "L"
    • Actual Batch Yield: 1
    • Expiration Date: Note that this has been auto-filled, based on the Mixture's expiration property.
    • Materials/Ingredient Source: Known
    • Amounts/Raw Materials: Known
    • Click Bulk Upload.
    • Copy-and-paste the following materials list into the text box, overwriting the pre-populated text. For simplicity, we have used 'unknown' raw ingredients instead of specific lot numbers already known to the registry.
IngredientAmount UsedRaw Material Used
Sodium Chloride80unknown
Potassium chloride2unknown
Sodium phosphate dibasic anhydrous14.4unknown
Potassium Phosphate monobasic2.4unknown
Calcium Chloride, Dihydrate, Granular1.33unknown
Magnesium chloride anhydrous1unknown
    • Click Add Ingredients to submit the list.
    • Notice that the slider for Amounts/Raw Materials changed to Unknown.
    • Click Next.
  • On the Confirm tab, click Finish.
  • A details page for the new batch is displayed.
  • Click Batches
  • A table of batches is shown, including the new batch added in this tutorial.

Tutorial Curriculum

Biologics Tutorial: Register Samples

Biologics Tutorial: Create a New Biologics Project




Biologics Tutorial: Create a New Biologics Project


This tutorial shows you how to create a new, empty Biologics project and import your own data into it.

Set Up Trial Server

  • This tutorial assumes that you have registered and created a Biologics Trial instance of the server.
  • If you have already created a biologics trial server, select it, and login: Your Sites

Create a New Biologics Project

  • Navigate to the Home project of your trial server:
    • Click the product menu, click LabKey Server, then click LabKey Home.
  • Hover over the project menu and click the New Project button.
    • If you are using a trial server, you can click the Create panel to create a new project.
  • On the New Project page, enter a Name of your choice and select Biologics.
  • Click Next.
  • On the User Permissions page, click Next. For details on configuring security for your project see Security.
  • On the Project Settings page, click Finish.
  • The home page for LabKey Biologics will be displayed.

Import Your Own Data

Options for importing your own data:

Tutorial Curriculum

Biologics Tutorial: Work with Mixtures and Batches




Customizing Biologics: Purification Systems


This tutorial shows you how to extend LabKey Biologics to include purification workflows. To help you answer questions such as:
  • Which purification system (i.e., some combination of purification elements) is more efficient?
  • How does heat stress effect the quality of the drug substance?
Assume the following general workflow steps:
  • You have batches of broth from various expression systems. Purification of these samples produces a usable drug substance
  • A variety of purification regimens are available: different column designs, resins, AEX processes, and other experimental factors.
  • The drug substance is subjected to a variety of stress tests, such as heat tests, oxidation tests, etc.
  • Finally, MS2 experiments are performed, which rate the experimental factors (the purification regimens and stress tests) based on observed peptide modifications.

The following data model provides the LabKey data structures to capture the phases of experimental workflow.

The following tutorial gives you step by step instructions for capturing this experimental workflow in LabKey Biologics.

Download

  • Download the 4 example files below, used for assembling the workflow.
File NameDescription
SamplesPrePurification.txtSamples that come of out the bioreactor/expression system.
ListPurificationRegimens.txtVarious processes and workflows for purification of samples.
SamplesPostPurification.txtSamples that have passed through various purification regimens and are now to be stress tested.
AssayPeptideModifications1.txtMass spec assay result data.

Set Up Folder and Dashboard

  • On LabKey Server, navigate to a project where you have admin control.
  • Navigate to a subfolder or make a subfolder called "PurificationWorkflow". Below we assume a blank folder of type Assay, but you work in any folder type, for example a Biologics folder.
  • Enter > Page Admin Mode.
  • On the left side, add the Web Parts:
    • Assay List
    • Sample Types
    • Lists
  • Click Exit Admin Mode.

List

  • Create a List named 'PurificationRegimens'.
  • Infer fields, and import data from, the following data file: ListPurificationRegimens.txt
  • Select RegimenName as the primary key.

Sample Types

  • Create a Sample Type named 'PrePurificationSamples'.
  • Add the following fields:
    • Volume (Decimal)
    • Volume_units (Text)
  • Import the following data file: SamplesPrePurification.txt

  • Create a Sample Type named 'PostPurificationSamples'.
  • Add the following fields:
    • Volume (Decimal)
    • Volume_units (Text)
    • PurificationRegime (Lookup) -- point the lookup column to the List PurificationRegimens.
  • Import the following data file: SamplesPostPurification.txt

Assay Design

  • Create a new Assay Design called "PeptideModifications".
  • Remove the 6 default fields, in particular:
    • Remove the 2 Batch Fields.
    • Remove the 4 Result Fields.
  • Infer the Results Fields from the following file: AssayPeptideModifications1.txt. This should give you the following 6 fields:
    • Protein (Text)
    • Location (Text)
    • Modification (Text)
    • Experiment (Text)
    • Intensity (Decimal)
    • Rel. Intensity (Decimal)
  • Add the following Run Fields:
    • SampleId (Sample) - for the Sample Options, set Sample lookup to PostPurificationSamples
    • StressTemperature (Decimal)
  • Save the design.
  • Go the Runs or Result grids (which are currently empty) and click Import Data.
  • Set the Run fields as follows:
    • SampleId - Select some target sample from the dropdown, especially one of the PostPurificaiton samples.
    • StressTemperature - Enter a decimal value for the stress temperature, for example, 5, 25, or 40.
  • Import data from the same data file used above: AssayPeptideModifications1.txt
  • Import additional assay data in these files, selecting different SampleIds and Heat tests as you import:

Grid Modification

  • Go to the Assay result grid.
  • Open Grid views > Customize Grid
  • Open the nodes: Run > SampleId > PurificationRegimen.
  • Select the fields: RegimenName, AEXConductivity, ColProtein, Column, Resin.
  • Save this grid as the Default and select "Make this grid view available to all users".
  • Now you have a grid which you can query upon to compare the performance of the different regimens and stress tests.



Biologics: Terminology


This topic defines the entities in the Biologics registry, 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.

Diagram of Entity 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.

Example Molecules
Molecule W = 1 (protein sequence A)
Molecule X = 1 (protein sequence B) + 2 (protein sequence C)
Molecule Y = 1 (nucleotide sequence D)
Molecule Z = 2 (nucleotide sequence E) + 2 (protein sequence F) + 2 (molecule W)

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

Example Protein Sequences
protein sequence A = ACELKYHIKL CEEFGH
protein sequence B = HIKLMSTVWY EFGHILMNP

Nucleotide Sequence

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

Example Nucleotide Sequences
nucleotide sequence A (DNA) = AGCTGCGTGG GCACTCACGCT
nucleotide sequence B (RNA) = AGCUGUUGCA GCUUACAUCGU

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




Biologics: Projects and Folders


This topic is under construction for the 22.5 (May 2022) release of LabKey Biologics. For the previous version of this documentation, click here.

The LabKey Biologics application is designed to run in a project or folder on LabKey Server. This topic covers considerations for designing your system.

Support Multiple Biologics Containers

Biologics runs in the context of a project or folder, collectively known as containers. 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. 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 project or folder and keep all resources within it.

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 separate folders for the two groups. 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. By enabling the experimental feature "Subfolder data in LabKey Products", you can configure Biologics in a project with one or more Biologics subfolders. Definitions can be shared among the subfolders and permissions controlled independently. Users will see the entities and samples from folders to which they have been granted "Read" permissions.

Freezers 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 freezer access in this topic: Biologics: Shared Freezers

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, 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 project.

  • All Naming Patterns for Sample Types and Data Classes in the container will be updated to include the new prefix.
  • 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: Aliquot Naming Patterns.
To set a container prefix:
  • Select Settings from the user avatar menu.
  • Scroll down to the ID/Name Settings section.
  • Enter the prefix to use. You will see a preview of what a naming expression with the prefix applied might look like using a representative pattern, Blood-${GenId}, as an example.
  • Click Apply Prefix to apply it.
  • This action will change the Naming Pattern for all new and existing Sample Types and Data Classes. No existing IDs/Names will be affected. Are you sure you want to apply the prefix?
  • Click Yes, Save and Apply Prefix to continue.

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. This requires that every type of entity have a naming pattern that can be used to generate unique names for them.

When users are not permitted to create their own IDs/Names, the ID/Name field will be hidden during creation and update of rows, and when accessing the design of a new or existing Sample Type or Data Class.

Additionally:

  • Attempting to import new data will fail if an ID/Name is encountered.
  • Attempting to update existing rows during file import will also fail if an unrecognized/new ID/Name is encountered.
To disallow User-defined IDs/Names:
  • Select Settings from the user avatar menu.
  • Scroll down to ID/Name Settings.
  • Uncheck the box Allow users to create/import their own IDs/Names.
    • Note that to complete this change, all entities in the system must have a valid naming pattern. You will see a warning if any need to be added.

Related Topics




Biologics: Bioregistry





Biologics: Search Options


This topic is under construction for the 22.5 (May 2022) release of LabKey Biologics. For the previous version of this documentation, click here.

You can search the Biologics Registry in the following ways:

Note: If you use a '-' hyphen as a name separator element (as shown in the example below), search will interpret it as a minus, or NOT operator. The hyphen also breaks the search term into two elements. To search for a name with a hyphen you need to surround the search term with double quotes.
  • Searching for "es-1" will find the expression system ES-1 and related elements.
  • Searching for es-1 without the quotes will return results that contain "es" and not "1". This will include the "es-1" element (because it does not contain the string "1") but will also return many unrelated results that only contain "es".

Application-Wide Search

To search the entire application, including Bioregistry entities, Samples, and Notebooks, enter your search terms in the search box in the header.

Results are displayed as tiles, as shown below.

Click Advanced to filter by Entity Type. The dropdown is populated by the entity types known to the system, it is not limited to those in the existing results.

Select the desired type and click Search. Results will be filtered to only the entity type selected.

Search for Samples in Bulk

Using the dropdown menu to the right of the search box, you can:

Learn more in the companion topic for the Sample Manager application:

Sample Finder

This feature is under active development and will be expanded to support more scenarios and deeper ancestry searches in future releases.

Use the Sample Finder tool to search for samples based on filter criteria using:

  • Registry Parent Properties: Properties of direct-parent Bioregistry entities like a Molecule or Expression System from which the samples were drawn.
  • Sample Parent Properties: Properties of parent samples and/or raw materials.

Open the Registry/Sample Parent Properties tile(s) to see a full listing of candidate types and fields. You can add filtering criteria tiles for as many registry or sample parent types as needed.

The set of samples matching the criteria will be shown as you build your filters. Note that if you leave and reenter the Sample Finder, your accumulated criteria will be retained.

Learn more in the companion topic for Sample Manager.

Grid Search "Omnibox"

This feature will be removed in a future release in favor of an improved grid filtering interface.

An "omnibox" search bar appears above all grid views. Look for the placeholder text "Select...". For example, if you select Menu > Registry > Protein Sequences you will see:

You can enter multiple criteria in the search bar, clicking to select from the menu, then adding any number of filters, keywords, and sorts.

Filter Columns

Enter an expression consisting of a column, a comparator, and a value. The selection menus will present the list of available options to assist you. Once filtered, the grid will display only those rows where the expression is true (for the selected column). The screenshot below shows the Avg. Mass column filtered to show values greater than 20000.

To add a new filter, search, or sort, click in the search bar outside the filter expression.

Search Keywords

To add a keyword search, click anywhere in the search bar outside existing 'lozenges' for filters or sorts. You can simply type the keyword to search for, or select search keywords, then type into the search bar.

Keyword searches behave like substring searches across all of the rows in the table, not just the rows currently displayed in the browser. But the search is limited to only those columns that are currently visible in the browser. Hidden columns are not searched. To control which columns are visible and which are hidden, see Biologics Admin: Grids, Detail Pages, and Entry Forms.

Sort Columns

Sorts control the order in which rows are displayed. Below we have sorted the Name column 'ascending', i.e. from low to high values. Note that for a text column like "Name", this is an alphabetical sort, not numerical. You can see "PS-9" listed last here.

  • You can also control the sort order by clicking the icon in the column headers.

Data Grids

Data grids provide a column of checkboxes on the left for selecting each individual row. Check the box in the header row to select all rows on the current page.

Once you've selected a page of rows, you will see buttons to select all the rows on all pages, or clear those already checked.

In the upper right, you see which rows you are viewing (here 1-20 of 37). Buttons give you the following control:

  • Step one page forward or back using the "<" and ">" buttons. Shown here, the 'Previous page' button is grayed out when you are on the first page.
  • The page number you are on is shown with a dropdown menu. You can jump to the first page or last page and see a count of the total number of pages.
  • Click the page size button to change how the grid is paginated. Options: 20, 40, 100, 250, 400.

Video Resource




Create and Edit Entities


This topic is under construction for the 22.5 (May 2022) release of LabKey Biologics. For the previous version of this documentation, click here.

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

Create Entities in the User Interface

In this example, we show creation of a new cell line. Other kinds of entities 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 entity to create. Then select Create > [Entity Name].
  • 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 data class.
  • Description: Optional, but will be shown in the grids and can be a helpful way to illustrate the entity.
  • When the fields are completed, click Finish to create the new entity.

You can now return to the grid for this data class (i.e. cell lines) to find your new entity later.

Create/Import/Update from File

For bulk registration of many entities in Biologics, including registry data class members, 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.

Obtain Template

Obtain a template by opening the type of entity you want to create, then clicking Template.

You can also find the download template button on the overview grids for each Bioregistry data class, and the main Sample Types and Assay listings. If you wait until you are importing data from a file, you can also find the Template button in the import interface.

Use the downloaded template as a basis for your import file. It will include all possible columns and will exclude unnecessary ones. You may not need to populate every column of the template when you import data.

  • For example, for a Sample Type, if you have defined Parent aliases, all the possible columns will be included in the template, but only the ones you are using need to be included.
  • In cases of columns that cannot be edited directly (such as the Storage Status of a sample, which is defined by a sample having a location and not being checked out), these columns will be omitted from the template.
  • Note that the template for assay designs includes the results columns, but not the run or batch ones.

Import Data From File

For Bioregistry entities, Samples, Assays, and Ingredients and Raw Materials, you can select Manage > Import Data to use the file import method of creation. The Upload Files tab is selected by default; you can also Copy-and-Paste Data. Starting from the template makes file import easier.

Entity Naming Patterns

If you do not provide a name, the naming pattern for the data class will be used to generate one. Hover over the to see the naming pattern in a tooltip.

The default naming patterns in LabKey Biologics are:

EntityDefault Naming Pattern
Molecule SetsMS-${genId}
MoleculesM-${genId}
Molecular SpeciesMSp-${genId}
Protein SequencePS-${genId}
Nucleotide SequenceNS-${genId}
Expression SystemES-${genId}
ConstructsC-${genId}
VectorsV-${genId}
Cell LinesCL-${genId}

To change a naming pattern, edit the Data Class definition.

Edit Entity Details

Open the details page for the entity by clicking its name on the grid for the data class. You will see Details, Samples, and Related Entities on the Overview tab.

  • Click to edit details.
  • Authorized users can edit the Name here, as well as other details shown in the panel.

Hide Name Entry/Edit Options

An administrator can hide the Name field for insert, update, or both by using Query Metadata overrides on a data class basis.

  • When insert of names is hidden, they will be generated using the naming pattern for the data class.
  • When update of names is hidden, names remain static after entity creation.
For example, to hide the Name field for cell lines for both insert and update use the following:

<tables xmlns="http://labkey.org/data/xml">
<table tableName="CellLine" tableDbType="NOT_IN_DB">
<columns>
<column columnName="Name">
<shownInInsertView>false</shownInInsertView>
<shownInUpdateView>false</shownInUpdateView>
</column>
</columns>
</table>
</tables>

An administrator can also disallow user-defined names throughout the system as described in this topic:

Related Topics




Register Nucleotide Sequences


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

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:

The wizard has two tabs:

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.
  • 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
Click Next to continue.

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


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 and Edit Entities. To register entities using the API, or to bulk import sequences from an Excel spreadsheet, see Use the Registry API. You can enter the Protein Sequence wizard in a number of ways:
  • 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 Create > Protein Sequence.

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'.
Click Next to continue.

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
Editing is not allowed at this point, but you can edit annotations after the registration wizard is complete.

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




Register Leaders, Linkers, and Tags


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 Create > Protein Sequence.
  • This will start the wizard Register A New Protein Sequence.
On the Details tab, select the sequence type in the Seq Part field.
    • Leader
    • Linker
    • Tag
  • Click Next.
  • On the Sequence tab, scroll down and click Manually add a sequence.
  • Enter the sequence and click Next.

Related Topics




Register Molecules


This topic shows how to register a new molecule using the graphical user interface. To register molecules in bulk via file import, see Create and Edit Entities. Other ways to register molecules are to:

Create a Molecule

To add a new molecule to the registry:

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.
  • 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 (right-chevron) to expand (the colors will reverse and chevron will point down to indicate an expanded panel).

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
  • S-S bonds
  • Structure Format: Select a format from the pulldown list. The list is populated from the StructureFormat table.
A warning will be displayed if no antibody regions are detected by the system.

Click Next to continue.

Confirm

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

The new molecule will be added to the grid.

Related Topics

Also See



Protein Sequence Annotations


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:

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.

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.

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.

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




CoreAb Sequence Classification


Biologics Feature - This topic covers CoreAb Sequence Classification using LabKey Biologics. Learn more or contact LabKey.

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: White Paper Introduction

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

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




Molecule Sets and Molecular Species


Overview

Molecule Sets serve to group together Molecules (ex: antibodies or proteins) around common portions of protein sequences, once signal or leader peptides have been cleaved. Molecule Sets serve as the "common name" for a set of molecules. Many Molecules may be grouped together in a single Molecule Set.

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.

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

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.
When the molecule contains anything in addition to protein sequences, then:
  • 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”
For molecular species that are auto-generated, if it is using already existing protein sequences (one or more) as the components of that molecular species, they have appended Descriptions based on where it came from:
  • Mature of “PS-17”
  • Mature, desK of “PS-18”

Related Topics




Vectors, Constructs, Cell Lines, and Expression Systems


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

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

Create within the User Interface

Select the desired entity from the main menu, or access the creation wizard for any entity from the page for any other entity. For example, when you are viewing the Vectors grid, you can select Create > Vector, or use Create > Registry to expand the listing and select another entity type to create.

  • Create > Vector
  • Create > Registry > Construct
  • Create > Registry > Cell Line
  • Create > Registry > Expression System
The default fields for each entity type are shown below. General instructions for creating entities are in this topic: Create and Edit Entities

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 Admin: Grids, Detail Pages, and Entry Forms.

Entity TypeDefault Fields
VectorName
Description
Alias
Sequence
Selection Methods
Vector Parents
ConstructName
Description
Alias
Vector
Cloning Site
Complete Sequence
Insert Sequences
Construct Parents
Cell LinesName
Description
Alias
Expression System
Stable
Clonal
Organisms
Cell Line Parents
Expression SystemsName
Description
Alias
Host Cell Line
Constructs
Expression System Parents

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. Learn more in this topic:

Related Topics




Entity Lineage


View Lineage

Any parents and children of an entity (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 including 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




Customize the Bioregistry


This topic covers how an administrator can create new Data Classes in the Bioregistry and edit the fields in the existing data classes, including all built in Registry entity types and Media designs.

Definitions

The term Data Class 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 of a Data Class, though if you access these structures outside the application you will be able to see them.

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

Edit Existing Data Classes

The default set of data classes 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 as follows.

Open the desired data class from the main menu. All entries under Registry and Media are editable. From the menu, select Edit [Data Class] Design. In this example, we'll edit the Molecules design:

You cannot edit the Name of a data class, but can update the Description and Naming Pattern if desired.

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. For example, you cannot change either the name or lookup definition for the "moleculeSetId" field shown below, but you could expand the field and change the label so that it had a different column heading in your grids.

When finished click Finish Editing [Data Class] in the lower right.

Create New Registry Type

From the main menu, click the Registry heading. Select Create > Registry Type.

Define the Data Class Properties:

  • Name: (Required) Must be unique and cannot be changed after data class creation.
  • Description
  • Naming Pattern: Naming patterns are used to generate unique IDs for every member of this type.
    • Learn more in this topic: Naming Patterns.
    • 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, etc).
    • For example, to use "DC-" followed by the date portion of the time the entity is added, plus an incrementing number you could use:
      DC-${now:date}-${genId}
Click the Fields section to open it, then import, infer or manually define the fields you need using the field editor.

When finished, click Finish Creating Data Class. Your new class will now appear on the registry dashboard with a default 'ring' icon.

Note that the main menu will not list your new class directly, you'll click See all ## at the bottom of the list to find it on the main dashboard.

Delete Custom Registry Type

You cannot delete the built in Registry (or Media) types, but if you add a new custom one, you will have the ability to delete it.

Click Registry on the main menu, then click the tile for the custom registry type to delete. Select > Delete [Registry Type]**.

Deleting a data class cannot be undone and will delete all members of the class as well. You will be asked to confirm the action before it completes.

Related Topics




Bulk Registration of Entities


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.

You can bulk upload the following entity types:
  • Cell Lines
  • Molecules
  • Nucleotide Sequences
  • Protein Sequences
  • Vectors
  • Constructs
  • Expression Systems

Supported File Formats

Tabular file formats are supported for all entity types:

  • Excel: .xls, .xlsx
  • Text: .csv, .tsv
Nucleotide sequences, protein sequences and constructs can also be imported using GenBank file formats:
  • GenBank: .genbank, .gb, .gbk
LabKey Biologics parses GenBank files for sequences and associated annotation features. When importing GenBank files, corresponding entities, such as new nucleotide and protein sequences, are added to the registry.

Assemble Bulk Entity Data

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

Bulk Upload Entity Data

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

  • Go the entity type you wish to import.
  • Select Manage > Import Data.
  • On the Import page, either Upload Files or Copy-and-Paste Data using the tabs.
    • If you stay on the Upload Files tab, drag and drop your file into the target area and click Finish.
    • If you select the Copy-and-paste Data tab, select TSV or CSV as appropriate, copy and paste your data (including the header row) into the text box, and click Finish.

Bulk Data Example Files

Example Nucleotide Sequence File

Notes:

  • Annotations: Add annotation data using a JSON snippet, format is shown below.
namealiasdescriptionflagprotSequencessequenceannotations
NS-23Signal Peptide 1An important sequence.FALSE[{name: "PS-23"}]CCCCTCCTTG
GAGGCGCGCA
ATCATACAAC
CGGGCACATG
ATGCGTACGC
CCGTCCAGTA
CGCCCACCTC
CGCGGGCCCG
GTCCGAGAGC
TGGAAGGGCA
[  
{
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:

namealiasdescriptionflagprotSequencessequenceannotations
NS-100Signal Peptide 1some descriptionFALSE[{name: "PS-100", nucleotideStart=1, nucleotideEnd=30, translationFrame=2}]ATGGAGTTGGGACTGAGCTGGATTTTCCTTTTGGCTATTTTAAAAGGTGTCCAGTGT 

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 ().
NameAliasDescriptionNuc SequencesChain FormatAvg. MasspI?%?Num. S-SNum. CysOrganismsSequence
PStest-150 Test sequence for import 113999.648.030355002.5412[mouse, rat]EVQLVESGEL
IVISLIVESS
PSSLSGGLVQ
GGGSLRLSCA
ASGELIVISL
IVESSPSSLS
YSFTGHWMNW
VRQAPGKGLE
WVGIMIHPSD
SETRYNQKFK
DELIVISLIV
ESSPSSLSIR
FTISVDKSKN
TLYLQMNSLR
AEDTAVYYCA
RIGIYFYGTT
YFDYIWGQGT

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

TypeIngredient/MixtureAmount Unit Type
IngredientI-2unknown

Batch Bulk Upload

IngredientAmount UsedRaw Material Used
Sodium phosphate dibasic anhydrous5RawMat-1234
Sodium Chlorideunknownunknown
Potassium chlorideunknownunknown

Downloadable Example Files

Download a sample file for a given entity type:

Related Topics




Use the Registry API


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

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 molecule, 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.
  • Upload an Excel file or paste in text (select tsv or csv) in the format:
DescriptionprotSeqIdtranslationFrametranslationStarttranslationEndsequence
Anti_IGF-1PS-7000caggtg...

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.
  • Paste in a TSV file or upload an Excel file in the format below.
NameDescriptionchainFormatIdorganismssequence
PS-1PS1038-11["human","mouse"]MALWMRL...

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:
DescriptionstructureFormatIdseqTypecomponents
description11[{type: "nucleotide", name: "NS-1", stoichiometry: 3}]
description13[{type: "protein", name: "PS-1", stoichiometry: 2}, {type: "protein", ident: "ips:1234"}]
description13[{type: "chemical", name: "CH-1"}, {type: "molecule", name: "M-1"}]

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 details 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




Biologics: Samples


This topic is under construction for the 22.5 (May 2022) release of LabKey Biologics. For the previous version of this documentation, click here.

LabKey Biologics represents materials in various phases of bioprocessing using Samples. Samples of many different types can be defined to represent your development process. They can be standalone compounds, they can have parentage/lineage, they can be aliquoted, used to derive new samples, or pooled. The lineage of samples you track may be both concretely real (such as a parent material or vial) and virtual (such as a Recipe and/or an Expression System used).

Sample Types define the fields and properties for the different kinds of samples in your system.

Sample Types Dashboard

In the LabKey Biologics application, the Sample Types dashboard displays an overview of all the samples known to the system.

Sample Types can be created and edited either inside or outside of the Biologics Application. From this page you can download a template for any type of sample to make importing samples from file easier.

Click the name of a Sample Type to see details about the type, including how new names will be generated, a panel of sample type Insights, and a grid of all SampleIDs registered of this type. Menus are provided for:

  • Create: Presents the list of what you can create from here, including new Samples of any existing type.
  • Manage: Actions available here include importing samples from file, deleting, and editing in grid or bulk.
  • Jobs: Start a workflow job. If any samples are selected, you can also add them to a new or existing job.
  • Storage: Users with the "Storage Editor" role can manage sample storage here.
  • Charts: If charts are defined for this kind of sample, you can open them from here.
  • Paging controls.
  • : Download in Excel, CSV, or TSV formats.
  • Grid Views: Select from any custom grid views offered for this kind of sample.
Below the menus, the omnibox offers searching, sorting, and filtering like other grids in the system.

Sample Type Insights

The panel of Insights gives a quick visual summary of Storage Status, Sample Status, and Aliquots. Color coded bars show the relative prevalence of each state. Hover for details, shown here, how many samples are checked out. Click any bar segment to filter the samples grid to show only those samples.

Learn more in the companion topic for Sample Manager.

Sample Details

Click an individual SampleID value to see details for that sample. A sample details page shows five tabs:

  • Overview: Summary of sample and parent information.
  • Lineage: Shows the parents and children of the current sample.
  • Aliquots: Shows all aliquots created from this sample (if any).
  • Assays: Displays any assay data associated with this sample.
  • Jobs: Shows all jobs involving this sample.
A brief summary of each is shown below. More details are available in the Sample Manager documentation.

Overview

The overview tab shows the values of all properties for the sample. Panels for Storage Location and Aliquots give details specific to this sample.

Use the menu to:

  • Create Samples (of any Sample Type): Only creation of derivatives is supported here. By default this sample will be a parent of the new one(s).
  • Add to Picklist
  • Create Picklist
  • Create Workflow Job: By default this sample will be automatically assigned to the job.
  • Upload Assay Data (for any Assay)
  • Delete Sample: Available only when samples do not have dependents like derived samples, assay data, or status that prevents deletion.
  • Check Out
  • Discard from Storage

Parent Details

Below the panel of details about this sample, you will see a panel of Parent Details giving the type and property values for the parent from which this sample was created.

Users with appropriate permissions can edit the parent details here when appropriate, changing parents, adding additional "parents" of other types, etc.

Lineage

Sample lineage is available as a graphical view by default, as shown below. Hover over any node for more information, click any node to see details. Click Go To Lineage Grid to see the same information as a grid. Learn more in the topic: Entity Lineage.

Aliquots

A grid of all the aliquots created from this sample. Learn more about creating aliquots in the Sample Manager documentation.

The Aliquot Naming Pattern is part of the sample type definition. The default is the parent sample name (AliquotedFrom) followed by a dash and incrementing counter:

${${AliquotedFrom}-:withCounter}

If instead you wanted to use a dot between the sample name and aliquot number, you'd use the pattern:

${${AliquotedFrom}.:withCounter}

Learn more about customizing aliquot naming patterns here: Aliquot Naming Patterns

Assays

On the Assays tab, you can see all the assay data available for that sample, as well as for all aliquots (and subaliquots) created from it. Click the assay name to see all results for that assay for the sample you are viewing. Select whether grids include data for samples, aliquots of those samples, or both.

Jobs

A grid of links to all the jobs that involve this sample, if any. Click Start a New Job to create a new one with this sample as an input.

Sample Status

The status of samples can be tracked using customizable Sample Status values. There are three main types of status:

  • Available: Can be used.
  • Consumed: Used up, and can longer can be aliquoted or checked out, but remains in the system for analysis and tracking.
  • Locked: Not currently available; some actions are prevented.
Learn more in the Sample Manager companion topic for this feature.

Use Status Settings

Users can assign statuses to their samples throughout the system:

  • At sample creation
  • During file import of new or updated samples
  • When updating a single sample's details
  • In a bulk sample update
Aliquots can have status values separate from their parent sample.

Manage Status Options

From the main menu, click Sample Types then click Manage Sample Statuses. Scroll down to find the current status settings defined.

Sample Status Legend

In many places in the application, users can access a legend of available status values. Hover over the for the Status column or field to see a legend listing all the available status values and their color coding.

Sample Picklists

When working with samples, it can be convenient to create user-defined picklists for gathering a set together for some operation like adding to a workflow job, adding to storage, performing bulk operations, etc. You can add samples to picklists from many places in the application, and create new ones as needed on the fly. A user can build a picklist privately, adding and removing samples until the correct set are defined, or share with the team so that everyone can work from the same list.

Access the picklists dashboard from the user menu:

Sample Grids Containing Samples of Several Types

Some sample grids, including picklists, workflow sample lists, and lineage listings of descendent samples, may contain samples of more than one sample type. These grids will offer a set of tabs:

  • All Samples: A listing of all samples on the list, with system fields common to any sample type.
  • Specific Sample Types: The type-specific listings will show, and allow updating of, properties of the specific sample type.

For example, menus on the picklist grid offer:

Sample Finder

Use the Sample Finder tool to search for samples based on attributes of their parents and/or components.

Learn more in these topics:

Related Topics

LabKey Server Documentation about Samples




Biologics: Create Samples


This topic is under construction for the 22.5 (May 2022) release of LabKey Biologics. For the previous version of this documentation, click here.

To create new samples within LabKey Biologics, you must first create the Sample Type to describe the properties this kind of sample will have.

Once the type exists, you can create or import data for new samples, using grid and file import interfaces described here.

Topics

Create Sample Type

The Sample Type defines the fields and properties of samples. You can create Sample Types either inside or outside the LabKey Biologics application.

To create Sample Types inside the Biologics Application, click Sample Types on the main menu, then select Create > Sample Type.

  • Note that before any Sample Types are created, the main menu will include a direct link to "Create a Sample Type".

Follow the Sample Type creation process, as described in this topic for the LabKey Sample Manager application:

Once you specify all the properties and fields, click Finish Creating Sample Type and it will be available for use in the application.

Learn about about the different field types available in this topic: Field Types and Properties Special behavior for File fields in Sample Types is described in this topic: Attach Images and Other Files

Naming Patterns

Samples must have unique names (SampleIDs). These can be provided by you or generated by the system using a Naming Pattern as part of the definition of the Sample Type. Naming patterns can incorporate column values, dates, strings, and lineage details. Learn more in this topic:

Aliquot Naming Patterns are also defined for the sample type. The default is the parent sample name (AliquotedFrom) followed by a dash and incrementing counter:
${${AliquotedFrom}-:withCounter}

If instead you wanted to use a dot between the sample name and aliquot number, you'd use the pattern:

${${AliquotedFrom}.:withCounter}

Learn more about customizing aliquot naming patterns here: Aliquot Naming Patterns

Both Sample and Aliquot naming patterns will be validated during sample type creation, giving administrators a chance to correct any syntax errors. Users will be able to hover over the to see an example generated ID in a tool tip within the application when creating new samples or viewing the details for a sample type.

Create Samples

There are several entry points from which you can create samples of any given type.

  • From an entity or sample detail page: Select > Create Samples > [Type of Sample] to create samples of any type. See below.
  • From a grid of samples of any type: Select Create > [Type of Sample].
  • From a grid of another kind of entity: Select Create > Samples > [Type of Sample].

Create Samples from Selected Parent

When you create samples from an entity detail page, or select only one entity on a grid first, you will see a popup asking whether you want to create:

  • Derivatives: One or more output samples per parent, potentially with different properties.
  • Aliquots: Aliquot copies from the parent sample, sharing many of the same properties.
For both, enter how many new samples per parent you want to create:

Enter the number, then click Go To Sample Creation Grid. You'll see the parent entity prepopulated, and can edit this if necessary.

Learn more in the companion topic for Sample Manager:

Create Samples from Multiple Parents

If you select one or more entities from a grid before creating your samples, you will first choose whether you intend to create:

  • Derivatives: new samples from each of these parents separately, or
  • Pooled Samples: some number of new samples, each with all of the selected parents, or
  • Aliquots: aliquot copies of each of the parent samples.

Provide the number to create (for derivatives and aliquots this is the number per parent), then click Go To Sample Creation Grid to continue creating the new samples with prepopulated parents.

Learn more in the companion topic for Sample Manager:

Sample Creation Wizard

The fields required for creating new samples will vary based on the Sample Type. All new samples require:

  • Sample Type: Selected or prepopulated via one of the methods for entering the wizard.
  • Quantity to create.
You can either Create Samples from Grid or Import Samples from File. More details for both options are found in the companion topic for the LabKey Sample Manager application:

Parents

If desired, one or more parents of the new sample can be specified. Click Add Parent, then select the type of parent to be added from the list of Data Classes and Sample Types available. More than one type of parent may be selected if needed, and there is no requirement that each new sample have parents from every type selected.

If you are generating new sample IDs from an existing sample or entity, it will already be prepopulated as a parent, with the type of entity preselected as a parent type.

Generating Samples

Once the fields in the wizard are completed, click Finish Creating # Samples to generate the new samples.

Upon successful submission, you will see the sample type filtered to show only your newly created samples.

Import Samples from File

Instead of using the "Create" options and choosing "Import Samples from File", you can directly access this option by navigating to the type of sample you are importing and choosing Manage > Import Samples.

Using a downloaded template for your Sample Type makes it easy to import data in the expected format from file.

Follow the steps in the companion topic for Sample Manager:

Click Import to create the samples.

Related Topics




Biologics: Manage Samples


The Samples dashboard shows the types of samples available. Click Sample Types on the main menu to reach this page. This topic describes working with Samples that are already registered in the system. To learn various methods for adding new Samples and Sample Types, see Biologics: Create Samples.

View All Sample Types

Sample Type names are listed on the left (and also directly accessible from the Sample Types section of the main menu).

View Samples of One Type

Click the sample type name link to see a grid view of all samples of that type. Details about the sample type, including the Description, Name Expression, and Parent Import Alias(es) (if any) are shown above the grid.

Use the omnibox to filter, sort, and search the grid.

Actions on the menus let you:

  • Create: Add new samples (or other entities in the system).
  • Manage: Including import, delete, and edit. You can also add a sample to a picklist.
  • Jobs: Add samples to workflow jobs.
  • Storage: (Available to users with the storage editor role.) Add samples to freezers, check them out or in, and discard when finished.
  • Charts: View any charts created in LabKey Server for this Sample Type.
  • Paging Controls.
  • Grid Views: Select among any custom grid views created in LabKey Server for this Sample Type.
  • Show Samples menu: Use checkboxes to select Samples and Aliquots. Possible values for this menu:
    • All Samples (both Samples and Aliquots)
    • Samples Only
    • Aliquots Only
Learn more about Aliquots in this topic for Sample Manager: Aliquots, Derivatives, and Sample Pooling

Edit Samples

You can edit multiple samples of a given type with two different interfaces. Edit in a grid to make individual changes to each sample row. Choose to edit in bulk if most of the values you are setting will be the same for all the edited samples.

Edit Selected Samples in Grid

This option opens a grid where you will see current data for all the selected samples.

  • Type directly in the grid to change Sample Data values as necessary. Note that you cannot change the Sample Id.
    • Fields that offer selection menus, such as Status, Text Choice fields, and list lookups, will show options on a menu. Type ahead to narrow the choices and click or tab to select.
  • Users with the "Storage Editor" role can switch to the Storage Details tab to edit the stored amount, units, and freeze thaw count for the selected samples. Any samples not currently in storage will not be editable here.

You cannot edit storage locations from this grid. Instead, navigate to the storage location of the sample to move it. Learn more in this Sample Manager topic: Move Stored Samples
  • Switch to the Lineage Details tab to edit parent information for these samples.
    • Edit existing parent relationships for these samples, or add a new type of parent by clicking Add Parent and choosing the type to add, then populating the rows in the grid.
    • Fields that offer multi-select will let you choose additional values from the menu.

Click Finish Updating # Samples when finished. The number you are editing will be included on the button.

Edit Selected Samples in Bulk

This option is useful when you want to change one of the columns of your sample data to the same value for a set of samples. Note that if you select any aliquots and choose this option, only the aliquot-editable fields will be shown for editing.

  • For each field that you want to update, click the Disabled/Enabled selector to set it to Enabled.
  • Enter the desired value, or to delete existing values enter nothing in the field.
  • Fields marked Disabled will not be changed.

Click Edit With Grid to open the grid editing interface with the values updated in bulk. You can continue to make further changes to individual rows in the grid before clicking Update Samples to save the changes.

Edit Parents for Selected Samples in Bulk

When you Edit Parents for Selected Samples in Bulk, any values provided will replace the existing parents of the chosen type(s) for the selected samples. Lineage for Aliquots cannot be changed and will be ignored if selected.

  • Select the Parent Type 1 that you want to replace for the selected samples.
  • Select the Parent ID to assign to the selected samples.
    • Note that if you leave this selection blank, it will remove any current values for that type of parent.
    • To choose multiple parents of the same type, select one, then click elsewhere in the entry box to reopen the selection menu.

To provide a new value for another Parent Type, click Add Parent and repeat the selection process for Parent Type 2

Click Update Parents when finished.

Delete Samples

You cannot delete samples once they have had other samples derived from them, or have assay data dependencies. If you attempt to delete samples with these conditions, you will see this information in a popup and be able to continue to delete any eligible samples of the once you selected.

To delete one or more samples:

Learn more about sample deletion and how dependency restrictions are handled, review this LabKey Server topic: View Sample Types and Samples.

View a Single Sample

From any Samples grid view, click a Sample Id (name) to see details of that sample. More information about what is shown on all the tabs is provided in this topic:

Edit Sample Details

On the Overview tab, you can click the under the title to add or edit the description. You'll see the Storage Location (if any) and Aliquots (if any) in panels below the title. Click the icons to edit details for this sample.

If your Sample Type includes a field of type File, you will be able to upload a file attachment in the Details panel here. Learn more in the Sample Manager documentation: Attach Images and Other Files

Edit Sample Lineage

To edit sample lineage, use the to edit the Parent Details panel.

Learn more in the Sample Manager documentation: Edit Sample Lineage

Related Topics




Sample Comparison Report


The Sample Comparison Report presents a view of assay data for selected samples, allowing you to compare samples between experiments and within the same experiment. Comparisons can be helpful for molecule candidate selection, experimental design, and quality control. For example, a sample comparison report that brings together antibody characteristics, transfection and clone identifiers, and assay data into a single view, can help inform design of the next experiment.

You can pass different groups of samples or experiments to the report to see specific results. Results can be filtered to display (1) only those samples related to a specific parent entity and/or (2) only results within a specific range of assay values. The report has three display modes: a details grid, a summary grid, and a graphical mode (scatter plot).

Create a Sample Comparison Report

To create a new report:

  • Select samples of interest and click Charts > Preview Sample Comparison Report.
    • OR
  • Navigate to an experiment and click Charts > Preview Sample Comparison Report.
  • The default report shows the first three columns of every assay for which there is data.

Refine the Report

You can filter the report by choosing a source parent entity and adding different combinations of value ranges. To filter which assays and fields are displayed, edit the JSON source directly.

In the example below, the report has been filtered down to the data pertaining to vector #1 and culture days 1-4.

You can also set ranges by directly drawing regions on the plot.

Save a Report

  • Save a report by clicking Save Report.
  • Enter a name, description, and click Save.

View Samples and Experiments in the Report

Once a report has been saved you can pass samples to it to view the results. To apply the report to selected samples, do the following:

  • Return to the Sample Type where you defined the report.
  • Select a group of samples.
  • Click Charts, and select the report name.

Edit JSON Source

Editing this report requires editing the JSON source. Scroll down to the bottom of the page and click Edit in LabKey.

Add, remove, reorder, and relabel field elements to control how assays are displayed. For example, the following JSON displays fields from two different assays:

{
"selectedColumns": [
{
"name": "SampleName",
"alias": "SampleName"
},
{
"name": "lactate",
"fieldKey": [
"lactate"
],
"type": "DOUBLE",
"schemaName": [
"assay",
"General",
"Lactate"
],
"queryName": "Data",
"sampleIdColumnName": "SampleId"
},
{
"name": "Culture Day (Lactate)",
"fieldKey": [
"cultureDay"
],
"type": "DOUBLE",
"schemaName": [
"assay",
"General",
"Lactate"
],
"queryName": "Data",
"sampleIdColumnName": "SampleId"
},
{
"name": "osmolarity",
"fieldKey": [
"osmolarity"
],
"type": "DOUBLE",
"schemaName": [
"assay",
"General",
"Osmolarity"
],
"queryName": "Data",
"sampleIdColumnName": "SampleId"
},
{
"name": "Culture Day (Osmolarity)",
"fieldKey": [
"cultureDay"
],
"type": "DOUBLE",
"schemaName": [
"assay",
"General",
"Osmolarity"
],
"queryName": "Data",
"sampleIdColumnName": "SampleId"
}
]
}

Related Topics




Biologics: Assay Data


Assay data is captured in LabKey Biologics 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.

SampleIDExpression RunSampleDateInjVolVialCal CurveIDDilutionResultIDMAb
2016_01_22-C3-12-B9-01ER-0052016-01-23302:A,19461881.0000478360.2000
2016_04_21-C7-73-B6-02ER-0052016-04-22302:B,19461881.0000478350.2300
2015_07_12-C5-39-B4-02ER-0042015-07-13302:C,19461881.0000478340.3000

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.

Topics for Administrators

Topics for Users




Biologics: Upload Assay Data


This topic is under construction for the 22.5 (May 2022) release of LabKey Biologics. For the previous version of this documentation, click here.

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 from a grid of samples, making it easy to enter data for those samples.

Import Assay Data

To import new assay data:

  • From the main menu, under Assays, click the name of the assay design you wish to import into.
  • On the Data Import page fill out the form:
  • Batch Details: (Optional) If the assay design includes batch fields, you will be prompted to enter values for them here.
  • Run Details: (Optional) Run fields include the Assay Id (name for this run) and also capture the characteristics of this assay experiment defined as run fields in the assay design. These may include such the instrument settings, special circumstances, or which request this data fulfills.
    • Assay Id: If no id is supplied, then the assay file name will be used. If no file name is used, then an id will be created from the assay design name plus a time stamp.
    • Comments: Add text to record special circumstances connected to this assay run.
    • Workflow Task: Select the workflow task associated with this run, if any.
    • Assay Request: Select the assay request, if any.
    • Other fields to populate may be shown here.
  • Results - There are three tabs in this panel. To help your data conform to the assay design, click Template to download a template to use.
    • Upload Files - On this tab (shown in the screencap above), you can either click to select your assay data file or you can drag and drop it directly onto the upload area.
    • Copy-and-paste Data - On this tab, you can copy-and-paste your data into a text box. Include column headers in what you paste. The maximum number of rows permitted via this method is 1000.
    • Enter Data Into Grid - On this tab, you have several options.
      • You can manually enter data into a grid. Select the desired number of rows and click Add rows, then populate with data. For lookup fields like Sample ID, you can type ahead and choose the right option.

      • You can click Bulk Insert to add a batch of assay rows that will share some set of properties.
      • After entering properties that will be shared, click Add Rows to Grid; you will then be able to customize individual rows in the grid editing interface.

      • After adding rows to the grid, either individually or via bulk insert, you can select one or more runs and choose Bulk Update.
      • In the popup, you can click the Disabled slider to Enabled, then enter a value for any row that the selected rows should share. For example, to give all selected rows the same Day, you might use the following. No values will be changed for fields left Disabled. Scroll down and click Finish Editing Rows.
      • After bulk editing rows, you will return to the grid view where you can make adjustments to individual rows if needed.
  • Once your data has been uploaded or rows entered, click Save and Finish or Save and Import Another Run.

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 Create > Assay Data > [Assay Design Name]. The menu will expand to show the assay options from which to select. 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 Save and Finish (or Save and Import Another Run).

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 (bars) menu and select Re-import Run.

Note that re-import of assay data is not supported for: file-based assay designs, ELISA, ELISpot, and FluoroSpot. If the reimport option is not available on the menu, the only way to reimport a run is to delete it and import it again from the original source file.
  • 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 Upload Files, Copy-and-Paste Data, 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 have several options:

  • From the overview page for the assay, select the run(s) to delete using the checkboxes.
  • Select Manage > Delete Selected Runs.

You can also delete a single run directly from the detail page for the run.

  • Go to the runs table for an assay, and click the run to delete.
  • Click the (bars) menu and select Delete Run.

For either option, you will be reminded that deletion of runs is permanent and cannot be undone. Confirm the action in the popup to actually delete the results.

Learn about editing and deleting individual results rows within a run in the topic Biologics: Work with Assay Data.

Related Topics




Biologics: Work with Assay Data


This topic is under construction for the 22.5 (May 2022) release of LabKey Biologics. For the previous version of this documentation, click here.

LabKey Biologics offers a number of different ways to work with assay data in the system. Administrators can control which options are available and to which users.

Assay Data Dashboards

Click Assays on the main menu to go to the assay dashboard. The default view is a grid listing the Assay Designs in the system with names, descriptions, and types. A button to download a template is provided for each assay.

Any archived, or inactive, assay designs are only included when you click the All tab.

You can click the Grid selector to choose a Heatmap view instead, in which the available assay designs are rows and the last twelve months are columns. Color density indicates the amount of assay data that has been entered into the system. Clicking a cell in the heat map navigates to the data for the given assay type and month.

Assay Design Details

Click the name of an Assay Design to see it's summary page, with several tabs, showing various scopes of the data:

  • Overview - Displays the name and description for the assay. A grid of runs is also shown.
  • Batches (If defined) - View batches, the widest grouping of the data. Each batch generally groups together multiple runs of data.
  • Runs - Displays run-level metadata about the assay results. Runs are the mid-level grouping of the data, standing between the batches and the result data. Each run generally represents one file of data.
  • Results - Displays the result data of the assay, showing the data output of the instrument.

On assay data grids, any visualizations that have been added to the assay, can be seen by clicking the Charts button. If the Charts button is grey-out, then no visualizations have been associated with the current assay at the selected scope. (Administrators can add charts to an assay, as detailed in the topic: Biologics Admin: Charts and Reports.)

Custom grid views are available by clicking the Grid Views button. (Administrators can add custom data grids to an assay at any level, as detailed in the topic: Biologics Admin: Charts and Reports.)

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 (Admin)

To configure states, an admin must:

  • Open the Assay Design where you want to use QC. Select > 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 project name] to switch interfaces.
  • Configure the available QC states in the system, using this topic: Assay QC States - Admin Guide.
    • Select (Admin) > 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 project name] to return to Biologics.

Use QC States (Users)

Once QC states have been configured in the system, users (with the appropriate roles) can assign those states to assay run data. Users can update QC states in the following cases:
  • when a user has both Reader and QC Analyst roles
    • OR
  • when a user has either Folder, Project, or Site Admin roles
To assign QC states within the Biologics application:

  • Navigate to the assay run view page. (Cell Viability runs are shown below.)
  • Select one or more runs.
  • Select Manage > Update QC States. (Admins will see Manage > Update QC States, while QC Analysts will see only the Update QC States button.)
  • 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:

Edit Assay Results

To edit assay results rows, access the rows of interest either by clicking the run name or the results page for the assay.

Select the rows of interest and select your option from the Manage menu:

  • Edit Selected Results in Grid: Start from a grid view of all the data for the selection; manually adjust as needed.
  • Edit Selected Results in Bulk: Assign one value for a field to all the selected rows. For example, if an incorrect Day was entered for a set of runs, you could correct it in one step.

For details about using the editors for these two methods of updating results rows, see the documentation for the same feature in LabKey Sample Manager

Delete Assay Results

Specific results rows within a run can be deleted from either the grid for a specific run, or for the results page for the assay as a whole. If you want to delete an entire assay run, learn how in this topic: Biologics: Upload Assay Data.

From the results grid, select the rows to delete and select Manage > Delete Selected Results.

You will be reminded that deletion of rows is permanent and cannot be undone. Confirm the action in the popup to actually delete the results.

Related Topics




Biologics: Media Registration


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

Topics




Registering Ingredients and Raw Materials


This topic is under construction for the 22.5 (May 2022) release of LabKey Biologics. For the previous version of this documentation, click here.

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.
  • Raw Materials are physical instances of an Ingredient, tangible things that have a location in storage, with specified amounts, sources, lot numbers, locations, vessels, etc.
There is a similar relationship between Mixtures and Batches.
  • Mixtures are definitions. Recipe definitions, instructions for combining Ingredients.
  • Batches are physical things, what you get when you combine Raw Materials according to some Mixure recipe.
This topic describes viewing registered media and steps for registration of ingredients and materials. The processes for creating mixtures and batches are covered elsewhere.

The Media dashboard provides tiles for registering and managing:

Ingredients

Clicking Ingredients brings you to a grid of available (previously created) ingredients. There is a Create > menu to create a new ones and Manage to import bulk data defining ingredients. Click Template to obtain an Excel template with the expected columns.

Selecting Create > Ingredient opens the wizard for creating a new ingredient. This wizard is controlled by the fields in the 'Ingredients' DataClass, which can be customized through LabKey Server by an administrator to include the fields you need. For example, the insert panel for ingredients might look like this:

Once required fields are completed, click Finish and you will see the grid filtered to show only your new ingredient. Click the 'X' on the filter to return to viewing all ingredients.

Raw Materials

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

Select Create > Raw Material to add a new one. The interface is similar to that for creating samples with options to:

  • Create Raw Materials from Grid
  • Use Bulk Import (shown below)
  • Use Bulk Update
  • Import Raw Materials from File
    • Use Template to download a template.

A quantity is required, a description is optional, and the other fields included are determined by the "RawMaterials" sample type.

  • Quantity (Required)
  • Alias
  • Description
  • Manufacturer
  • Product Number
  • Lot Number
  • Amount
  • Expiration Date
  • Consumed
  • Ingredient Name
If you select one or more Ingredients in the grid prior to selecting Create > Raw Materials, those ingredients will be prepopulated in the wizard.

Bulk Upload of Ingredients and Raw Materials

To upload ingredients and raw materials in bulk, select Manage > Import Data.

A variety of file formats are supported, including Excel and TSV files. Click Template to download a blank file with the appropriate column headings for import.

Related Topics




Registering Mixtures (Recipes)


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.
An analogous relationship exists between Ingredients and Raw Materials: Ingredients are the virtual definition of a substance (registered only one once); Raw Materials are the multiple physical instantiations of a given Ingredient.

Registering Mixtures

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

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:

You can also register mixtures of unknown ingredients, amounts, and concentrations; for example, when you receive materials from an outside vendor which does not disclose the ingredients, or only partially discloses them. To register mixtures with limited information see: Mixtures can also be added using a table of ingredients, that you copy-and-paste from an Excel or TSV file. For details see:

Start a New Mixture "From Scratch"

From the main menu, select Media, then Mixtures and then Create > Mixture above the grid of available mixtures.

Start from an Existing Mixture

Any of the registered mixtures can be clicked for a detailed view. The details view includes general information as well as the mixture’s included ingredients and preparation steps. The details page also includes a Create > Mixture menu in the which opens the create mixture wizard (and includes the current mixture within the wizard).

Start with an Existing Ingredient

Clicking Ingredients brings you to a grid of available (previously created) ingredients. Click an individual ingredient for a detailed view. Select Create > Mixture to open the wizard to create a new mixture which includes the current ingredient within the wizard.

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, g/mg, g/μg, mol/kg, mol/g, mol/mg, mol/μg
  • If Volume is selected, unit types will be: g/kL, g/L, g/mL, g/μL
Note that molar volumes are not allowed, as the ingredient wizard assumes molecular weight to be in g/mol. Since the registry does not record density, a conversion from g to mL is not possible.

Click Add Ingredient for each unique component of the 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.

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 minus button on the right 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 tablular format by copying-and-pasting from an Excel or TSV file.

  • Go to the Mixtures grid and select Create > Mixture.
  • 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 a template table 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. Columns are explained below:
    • 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: g/g, g/kg, mL/kg, mol/g, mol/kg
  • 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.

Selecting the Unknown on the toggle switch disables entry of any further details about the recipe:

Selecting an Unknown Amount checkbox 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.

  • In LabKey Server, go to the gear menu > Go to Module > Experiment.
  • Scroll down the list of Protocols.
  • Select the Protocols to delete, and click the trash can icon to delete.
  • You should now be able to delete the Mixture DataClass row.

Related Topics




Registering Batches


Batches

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.

To create a new batch, select Create > Batch from the batches grid, or select Create > Mixture Batch from any mixture detail page to include that mixture in your batch.

The steps in the batch creation wizard are similar to those in the mixture wizard.

Details

On the Details tab, the only required fields is the mixture (i.e., the recipe) to be used to create the batch. Optional fields are: Batch Name, Description, Vendor/Part Number, Consumed. If the Batch Name is not provided, it will be automatically assigned a unique name. 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.

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

Registering Batches with Unknowns

When registering batches, the Ingredients step includes the option to mark:

  • all materials as unknown
  • individual raw materials as unknown
  • individual amounts as unknown
This is useful when adding vendor supplied batches to the registry, where you may not know specific details about the vendor's proprietary materials and/or amounts.

Note the button Show unknown options. When clicked, the UI reveals "Unknown" checkboxes underneath each row's amount and raw material input. Selecting Unknown will then disable the individual input.

To disable all material and amount inputs, click to set the slider for Materials/Ingredient Source to Unknown.

Confirmation warnings are provided if the user provides incomplete values and an 'unknown' box is not ticked.

Once entered into the registry, the unknown factors are reflected in the user interface.

Bulk Registration of Batches That Include Unknowns

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

Related Topics




Biologics: Workflow


Biologics Workflow tools make it easy to plan and track your tasks with these lab workflow tools:
  • Create jobs to track and prioritize sequential tasks
  • Assign work to the right users
  • Use workflow templates to standardize common task sequences
  • Track progress toward completion
The Workflow section in the Biologics application provides flexible support for tracking any kind of workflow job and task. Design custom templates for repeated processes and assign task owners and individual due dates. Each user will see their own customized queue of tasks requiring their attention.

Job Overview

Completing Tasks involving Assays and Samples

When completing tasks involving assays, you'll see a pair of links for each assay involved in this task.

  • View Data: Once there has been data uploaded for this assay in this task, this link will take you to the filtered run.
  • Import Run: Open the importer for the requested assay.
    • By default you will see the Enter Data into Grid option, with rows prepopulated for the samples assigned to this job task, making it easy to manually enter values.
    • You can use bulk insert, file upload, or copy/paste import methods if desired.

Related Topics

Creating and managing jobs, templates, and task queues within Biologics is very similar to using the same tools in LabKey Sample Manager. More detailed documentation is available in the Sample Manager Help topics here:



Biologics: Create Workflow Job


This topic covers the basics of creating new Workflow Jobs in LabKey Biologics.
Creating jobs and templates within Biologics is very similar to using the same tools in LabKey Sample Manager. Additional documentation is available in the Sample Manager Help topics here:

Create a Job

You can create a new workflow job from many places within the Biologics application.

  • From the home page Jobs List, click Start a New Job.
  • Click Workflow on the main menu, then select Create > Workflow > Job.
  • From any entity grid, select Create > Workflow > Job.
If any templates are defined in the system, you can click Choose Job Template to select one and start with the jobs and files included in the template.

Job Details

Enter Job Details including:

  • Job Name
  • Description
  • Job Owner
  • Notify These Users
  • Job Start and Due Dates
  • Priority Level

In the Attachments section, upload any files that will be used for this job. This might include protocol documents or SOPs to accompany instructions in the tasks.

Tasks

In the Tasks panel, you can Add Task for each step that should be performed in this job. Each task has a name, optional description, "Assays to Perform", due date, and can be assigned to different users.

Input Samples

If this workflow job will be working with samples, you can assign them to the job to make it easier for user to find what they need to complete their tasks.

Click to open the Input Samples section, then Search for Samples. Options include a text search for samples or attributes, as well as a set of filters by:

  • Of Sample Type
  • From Parent
  • Created By
  • Date Range

Finish Creating Job

When ready, you can click Finish Creating Job or use the menu for more options:

  • Save as Template
  • Save as Template and Start Job

Learn more about creating jobs from templates below.

Create a Job from Selected Samples

On the grid for any Sample Type, you can select one or more samples, then select Jobs > Start a Job with Selected Samples.

This will create a new workflow job using the wizard as described above, prepopulating the Assigned Samples section with your selection. You can add additional samples as usual.

Create a Job from a Picklist

Using sample picklists gives you a method for 'gathering' a collection of samples, possibly of different types, on a list, then adding them together to a job.

  • Select Picklists from the user menu.
  • Click the name of the picklist to use; it may be on the Team Picklists list.
  • Select all or some of the samples from the picklist and select Jobs > Start a Job with Selected Samples.

Add Samples to Existing Job

If after job creation, you need to add additional samples, you can select them on the grid or picklist and select Jobs > Add Samples to Existing Job.

In the popup, select the job by name and click Add to Job.

Create Template From Job

Templates include the task definitions and file attachments, but not the user assignments, due dates, or samples. You can only create a template from a job during initial job creation. Either during the Finish Creating Job step or by clicking Save as Template during job creation. You give the template a name and save it for later use.

Create a New Job Template

From the Workflow dashboard or many other create menus in the application, select Create > Workflow > Job Template.

Creating a template is very similar to creating a workflow job, as described above.

  • Template Details: The template name and description, as well as any Attachments such as protocol documents, SOPs, or other materials that will be used whenever this template is used.
  • Tasks: As for a single job, create the tasks that will make up this job. Templates can include assays, but do not include specific user assignments.

Related Topics




Biologics: Process Parameters


This feature is under development for a future release of LabKey Biologics. It is currently available in development mode for evaluation.

LabKey Biologics administrators and lab managers use Process Parameters to manage the various inputs and that exist in the system for lab workflows. We want to provide them with a pathway other than the API to manage and set parameters. Note that we will likely learn there is much more needed and more to be done to make this management UI more powerful or useful.

Enable this Feature

Your server must be in devmode.

Select Enable Lab Processes from the user/avatar menu. If you do not see this option, this feature is not yet available on your server.

Define Process Parameters

Once enabled, select the Workflow dashboard from the main menu and click Manage Workflow Options. Click the Parameters tab. You'll see currently defined parameters listed.

Click Add New Parameter to add custom parameters, providing the necessary details in the panel to the right.

  • Parameter Name (Required)
  • Type (Required) Options are text, integer, date/Time, and boolean.
    • Once a parameter is in use, its type cannot be changed.
  • Default value (Optional) for any type other than boolean.
  • Value controls (Optional) for integer parameters only.
    • Range validation
Click Save Parameter when finished.

From the parameter listing, you can search parameters by substring in the box above the listing. Click the to execute the search.

Click the name of any parameter to see and edit details about it. Once a parameter is in use, you cannot change the type.

Use Process Parameters in Tasks

Tasks in workflow jobs can now prompt assignees to track the necessarily parameter values. To add process parameters to a task, you can edit the job or add them during initial job creation.

On the Tasks tab of the job creation wizard, you'll see a Parameters tab alongside task details. Click Add Parameters to select the ones you want your task assignee to track.

Type ahead to narrow the list and click to select the parameters to add. Click Add parameter to include it. When you have selected your parameters, click Apply Parameters to apply them to the job task.

Each task can have a different set of parameters, as required.

A task assignee later completing this task will be able to see and add job-specific values for them during task completion.

Related Topics




Biologics: Electronic Lab Notebooks


Within LabKey Biologics, use integrated and data-aware Electronic Lab Notebooks for documenting your experiments. 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. Select Notebooks from the main menu within Biologics.

Notebook Dashboard

On the dashboard, you will see summary cards for your most recently viewed notebooks, a summary of actions for you, and many ways to filter and find specific notebooks of interest. Learn more in this topic: Notebook Dashboard

Notebook Notifications

To enable or disable email notifications, select Settings from the user menu. Use the checkbox to subscribe:

  • Send me notifications when notebooks I am part of are submitted, approved, or have changes requested

When subscribed, you will receive email when notebooks you author are submitted, rejected, or approved. You will also receive a notification when you are assigned as a reviewer of someone else's notebook.

Emails sent will provide detail about the nature of the notification:

  • When a user starts a thread on a notebook:
    • The email subject field will follow the pattern: <USERNAME> commented in <NOTEBOOK NAME>: "<FIRST FIVE WORDS>..."
    • Recipients include: notebook author(s)
    • The thread author will not be in the notification list. If the thread author happens to be the same as the notebook author, this author will not get an email notification.
  • When a user comments on a thread:
    • The email subject field will follow the pattern: <USERNAME> replied in <NOTEBOOK NAME> on thread: "<FIRST FIVE WORDS OF ORIGINAL THREAD> ..."
    • Recipients include: notebook author(s) and the person who started the initial thread.
    • The current commentator shall not be in the notification list. If the commentator happens to be the same as the notebook author, this person will not get an email notification.
  • If a user's Messages setting at the folder level is set to "Daily digest of my conversations", then:
    • The individual email subject headers within the digest will follow the pattern: "<USERNAME> commented [...]" as specified above.
    • The subject-line of the digest email itself will not include comment details.
    • A notification will be included in a user's digest if they have participated in the thread, if they are on the notify list, or if they are among the authors of a notebook that has been commented on.

Topics

Video Overview

Learn more and see a preview of the ELN product by viewing the recording of the second day of the LabKey User Conference, starting around the 29 minute mark:




Notebook Dashboard


Using the Notebooks dashboard, you can track multiple simultaneous notebooks in progress and interactions among teams where users both author their own work and review notebooks created by others.

Notebook Dashboard

On the dashboard, you will see:

  • Your Recently Accessed: Summary cards for your most recently viewed notebooks. Click any card to see the full notebook.
  • For You: A summary of actions for you, with alert-coloring and the number of notebooks you have:
    • Overdue, waiting for you
    • Returned to you for changes
    • Awaiting your review
    • Submitted by you for review
  • Filter Notebooks: Use many ways to filter and find specific notebooks of interest.
  • All Notebooks: All notebooks in the system, with any filters you apply narrowing the list.

Filter Notebooks

There are many ways you can filter notebooks to find what you need:

  • Title, Description, or ID: Type to search for any word or partial word or ID that appears. When you enter the value, the list of notebooks will be searched. Add additional searches as needed; remove existing ones by clicking the 'x' in the lozenge for each.
  • Created: Enter the 'after' or 'before' date to find notebooks by creation date.
  • Authors: Type ahead to narrow the list of authors. Click to select. Add additional authors as needed to search; remove a filter by clicking the 'x' in the lozenge.
  • Reviewers: Type ahead to narrow the list of reviewers. Click to select. Add additional reviewers to the filter as needed; remove a filter by clicking the 'x' in the lozenge.
  • Review Deadline: Enter the 'after' or 'before' date to find notebooks by review deadline.
  • Projects: Type ahead to narrow the list of projects. Click to select. Add additional projects to the filter as needed; remove a filter by clicking the 'x' in the lozenge.
  • Status: Check one or more boxes to show notebooks by status:
    • Any status
    • In progress
    • Submitted
    • Returned for changes
    • Approved

All Notebooks Listing

The main array of notebooks on the page can be shown in either the Card View or Grid View. You'll see all the notebooks in the system, with any filters you have applied.

Sort notebooks by:

  • Newest
  • Oldest
  • Due Date

Switch to the Grid View to see details sorted and filtered by your choices.

Related Topics




Create a Notebook


This topic is under construction.

Notebooks give you a place to collaboratively record your research. You can have as many notebooks for as many projects as your team requires.

Create New Notebook

To create a new notebook, click Create New Notebook from the Notebooks dashboard.

  • Enter a Name.
  • Select the Project from the dropdown. Whether this field is required or optional is controlled by an administrator setting.
    • If you are an administrator, you can click Create new project to add a new project to the system.
  • Enter a Description.
  • Select Start and end dates.
  • By default, You are an author. Use the selection menu to add more Co-authors.
  • If you have templates defined, you can choose one to use by clicking Browse Templates.
  • Click Create Notebook.

Notebook ID Generation

When you create a new notebook, a unique ID value is generated for it. This can be used to help differentiate notebooks with similar names, and cannot be edited later. The format of this ID is:

ELN-{userID}-{date}-{incrementing counter}

For example, the user creating the notebook here has assigned User ID "1003", the date it was created was June 21, 2021, and it is the first one created in this project.

Create New Project

During notebook creation, the author can select an existing project. If that author is also an administrator, they have the option to click Create new project to add a new one.

  • Give the project a name, description, and set a color.
  • Click Create Project.

Learn more about projects in this topic:

Add Custom Fields

You can define and use custom fields for your notebooks to support additional classification that is meaningful to your team. Select the Custom Fields tab and use Add custom field to select an existing field to add to this notebook. Type ahead to narrow the list of existing fields to find the one you want. Shown here, the "ColumnTemperature" field is added and you can now provide a value for this field for this notebook.

To manage the set of custom fields available in your application, click Manage custom fields. In the popup you can see the existing defined fields and how many notebooks are currently using them. Here you can also add new fields, and edit or remove any fields not currently in use. Click Done Editing Fields when finished.

Rename a Notebook

A notebook author can select Rename from the menu next to the name. Non-authors will not see the Rename option on this menu. While the system does not require names to be unique, you will want to choose something that will help your colleagues identify it on lists and dashboards.

Copy a Notebook

Once you have created and populated a notebook, you can copy it to create a new notebook with the same details. This is similar to creating a new notebook from a template, except that templates do NOT include the value of any custom fields, and copied notebooks do include these values. You do not need to be a notebook author to make a copy of it.

Give your new notebook a name, select a project (the project of the one you copied is the default), and click Yes, Copy Notebook to create the new one.

Add to a Notebook

A notebook lets you record your work in a series of entries, each of which can have a custom name, span multiple days, include references to data in the Biologics application, and support entry-specific comment threads.

As you complete your notebook, everything is saved automatically. Note that refresh is not continuous, so if you are simultaneously editing with other authors, you may need to refresh your browser to see their work.

A new empty notebook looks like this:

The header section lists the name and ID, the authors, shows the project (if any), and shows the status. A details panel to the right summarizes references for all entries, may include attachments, and can be hidden by clicking Hide details (and shown again by clicking show details).

Add to an Entry

The New Entry panel is where you can begin to write your findings and other information to be recorded.

The formatting header bar for an entry includes:

  • Insert: Select to add:
  • Styling menu: Defaults to Normal and offers 3 heading levels
  • Special characters: Add mu, delta, angstrom, degree, or lambda characters
  • Bold, Italics, Underline
  • : Link selected text to the target of your choice
  • / : Make a text selection a super- or sub-script
  • Text color. Click to select
  • Alignment selections: Left, center, or right alignment; indent or dedent
  • Numbered or bullet lists
  • : Clear formatting

Rename an Entry

Click the next to the "New Entry" title to rename it.

Add a Reference

Within the entry panel, you can use the Insert > Reference menu, or within the text, just type a '/' forward slash to reference anything in the Biologics registry.

The / menu lets you select the category you want to reference:

If you click Samples you will next be able to click one of the existing Sample Types, then can type ahead to Search within that category, or the most recent entries in that category are shown.

Once added, the reference appears as a color-coded lozenge in the text, and is also added to the Referenced Items list in the details panel.

Add References in Bulk

After selecting the type of reference you want to add, you can click Reference multiple [type of reference].

In the popup, you can:

  • Paste (or type) your references into the box, one per line. Use sampleIDs as shown below, for example.
  • Click Upload file to upload a file of references, supported formats include .csv, .tsv, .txt
  • In the case of samples, assays, media, or registry entity references, click Change [category] to switch types within that category of reference.
Click Add References to add them.

If any pasted or uploaded references cannot be found, you'll see a warning listing the invalid references (valid references are not shown in the warning.

You can either:

  • Correct any errors and click Recheck References
  • Or click to Skip and Add References.

Add a New Day

Place the cursor where you want to add a marker for a new date. Select Insert > New Day. A date marker will be added to the panel for today's date.

Hover to reveal a delete icon. Click the day to open a calendar tool, letting you choose a different day to reference. Record activities for that day below the marker.

Comment on an Entry

Click Start a thread to add a comment to any entry. Each entry supports independent comment threads, and an entry may have multiple independent comment threads for different discussions.

By default you will enter comments in Markdown Mode; you can switch to Preview mode before saving. Other dashboard options include bold, italic, links, bullets, and numbered lists. Click the button to attach a file to your comment.

Type and format your comment, then click Add Comment.

Once your comment has been saved, you or other collaborators can click Reply to add to the thread. Or Start a thread to start a new discussion.

For each thread, there is a menu offering the options:

  • Edit comment (including adding or removing files attached to comments)
  • Delete thread

Add Attachments

Attachments, such as image files, protocol documents, or other material can be attached to the notebook.

To add an attachment to an entry, select Insert > Attachment. To add to the notebook as a whole, click the Attachments area in the Details panel on the right (or drag and drop attachments from your desktop).

Add a Table

You can add a table directly using the Insert > Table menu item, directly entering content. You can also paste directly from either Google Sheets or Excel either into that table, or into a plain text area and a table will be added for you.

Adjust Wide Tables

After adding a table to an ELN, you can add/remove columns using the table tools menu. Drag column borders to adjust widths for display.

When configured, you'll be able to export to PDF and adjust page layout settings to properly show wider tables.

Entry Locking and Protection

Many users can simultaneously collaborate on creating notebooks. Individual notebook entries are locked while any user is editing, so that another user will not be able to overwrite their work and will also not lose work of their own.

While you are editing an entry, you will periodically see that it is being saved in the header:

Other users looking at the same entry at the same time will be prevented from editing, and see your updates 'live' in the browser. A lock icon and the username of who is editing are shown in the grayed header while the entry is locked.

If another user attempts to edit an entry that is either actively being edited by another author OR has been updated since they opened it (or refreshed their browser), they will be prevented from making further changes. They will see a message reading "Unable to update this notebook entry. The entry you are attempting to edit appears to be out of date. Reload the page and try again."

Manage Entries

Your notebook can contain as many entries as needed to document your work. To add additional panels, click Add Entry at the bottom of the current notebook. You can also add a new entry by copying an existing entry.

Use the menu to:

Archive Entry

You cannot completely delete an entry in a notebook. Archiving an entry collapses and hides the entry.

  • You can immediately Undo this action if desired.
Once multiple entries have been archived, you can display them all again by selecting Archive > View Archived Entries at the top of the notebook. Each archived entry will have an option to Restore entry.

Return to the active entries using Archive > View Active Entries.

Copy Entry

Create a duplicate of the current entry, including all contents. It will be placed immediately following the entry you copied, and have the same name with "(Copy)" appended. You can change both the name and position.

Reorder Entries

Select to open a panel where you can drag and drop to rearrange the entries. Click Save in the popup to apply the changes.

Export Notebook as PDF

To export a notebook as a PDF, you must have correctly configured the Puppeteer service. Learn more in this topic: Configure Puppeteer.

Submit for Review

When your notebook is ready for review, click Submit for Review.

You'll review your entries, references, and attachments to confirm you have included everything necessary, then click Go to Signature Page.

Select one or more reviewers, provide a deadline, and comments if needed. You'll sign with your display name or email (click Configure name to set the display name to use). Check the box to certify that the data contained in the notebook is accurate. Click Submit Signed Notebook.

Learn more about the notebook review process in this topic:

Related Topics




Manage Projects


Notebooks can be organized and color coded by project, helping users group and prioritize their authoring and review work. New projects can be added during notebook creation.

Manage Projects

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

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

Delete Unused Project

To delete projects, an administrator can select one or more rows and click Delete. Projects with notebooks associated with them cannot be deleted.

Add New Project

To add a new project, an administrator clicks Create New Project, providing a name, identifying color, and optional description, then clicks Create Project.

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

Require Projects

By default, new notebooks do not require a project association. An administrator can require the selection of a project for every notebook using the Settings option from the user menu. Look for the Notebook Settings section.

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

Select Project for Notebook

Notebook authors will see the colors and names of projects available when they create or edit notebooks:

Related Topics




Notebook Review


This topic covers the process for reviewing and providing feedback to the authors on a notebook. Iteration of review and comment cycles will continue until all reviewers are satisfied with the contents of the notebook.

Review Notebook

When you are assigned as a reviewer for a notebook, you will receive a notification and see the notebook marked as Needs Review on the Notebook List.

Click the notebook card (or name on the grid) to open it. You'll see the notebook contents, including details, entries, references, etc. When ready to begin, click Start Review.

In review mode, you can check the contents of the notebook, adding Comments to specific entries if you like, viewing attachments, checking the linked references, etc. There are three actions available:

  • Close and go home: Conclude this session of review without making any decision. This notebook will remain the same status awaiting your review.
  • Suggest changes and return: Click to "reject" this notebook, returning it to the submitters with suggestions of changes.
  • Go to signature: Click to "approve" this notebook and proceed to the signature page.

Manage Reviewers

Anyone assigned the Editor role or above can be a reviewer of a notebook.

As the reviewer of a notebook, you also have the ability to add other reviewers, or remove yourself from the reviewer list if multiple reviewers are assigned. Open the notebook and click Manage reviewers.

Add reviewers by selecting them from the dropdown. Remove a reviewer by clicking the 'X' (at least one reviewer is required). Click Update Reviewers when finished.

Suggest Changes and Return (Reject this Version)

While in review mode, if you are not ready to approve the notebook, click Suggest changes and return. Provide comments and requests for changes in the popup, then click Yes, return notebook.

The authors will be notified of your request for changes. Your review comments will be shown in a new Review details panel at the top of the notebook.

This phase of your review is now complete. The notebook will be in a "returned for changes" state, and co-authors will be expected to address your comments before resubmitting for review.

Authors Respond to Feedback

When a notebook is returned for changes, the author(s) will see the Review details and be able to Unlock and update the notebook to address them.

After updating the notebook, the author(s) can again click Submit for Review and follow the same procedure as when they originally submitted the notebook.

Approve Notebook

As a reviewer in "review mode", when you are ready to approve the notebook, click Go to signature.

The signature page offers a space for any comments, and a Signature panel. Uses your display name or email address and checks the box to certify that the data contained in this notebook is accurate. Click Sign and approve.

The authors will be notified of the approval, and be able to view or export the signed notebook. The notebook will now be in the Approved state.

Approved notebooks cannot be edited, but if desired, they may be used to generate templates for new notebooks.

Related Topics

Related Topics




Notebook Templates


A notebook template provides a convenient way for researchers to begin their notebook with the sections and boilerplate content needed in your organization. Different types of notebooks for different purposes can be started from customized templates, making it more likely that final work meets the reviewers expectations.

Create New Template

To create a new template from scratch, click Templates on the main menu under Notebooks. You can also select Manage > Templates from the Notebooks Dashboard.

Click Create New Template.

Check the Sharing box if you want to create a Team Template, shared with other users in your lab. Click Edit Template to begin adding the starter content you want the template to contain.

Give your template a unique name so that you can locate it later. The default name, "New Template" includes a > Rename option.

Continue in template edit mode to add the content you want to be included in your template. Learn about creating, naming, populating, and arranging Entry panels in this topic: Create a Notebook.

Any references, attachments, and fields you include in the template will be available in any notebooks created from it. Notebook creators will be able to edit the content, so for example, you might include in a template directions for completing a "Conclusions" section, which the individual notebook creator would replace with their actual conclusions.

As you edit the template, saving is continuous. When you are finished making changes, click Lock Template to save this version.

Team Templates

To share your template with your team, check the Share this template with team members box. Team templates will be shown on a separate tab to all team members, and indicated with the icon.

Create Template from Notebook

You can also create a new template from an existing notebook. The template will include entry content, attachments, fields, and references for repeat use in other notebooks.

Open the notebook, the menu next to the title, then click Save As Template.

Give the template a name, check the sharing box if you want to share this template with team members, then click Yes, Save Template.

Create Template from Another Template

While editing a template, you can use the contents to create a new template by selecting Save As Template from the template name menu.

When you save the new template, you decide whether it is private or shared. The sharing setting for the new one does not need to match the source template.

Create Notebook from Template

To create a new notebook from a template, you have two options.

Starting from the template, click New Notebook From Template.

You can also start from the Notebook dashboard by clicking Create New Notebook. In the first panel, under Notebook Template, click Browse Templates.

In the popup, locate the template you want to use. Team templates are indicated with the icon.

Proceed to customize and populate your notebook. Note that once a notebook has been created, you cannot retroactively "apply" a template to it. Further, there is no ongoing connection between the template you use and the notebook. If the template is edited later, the notebook will not pick up those changes. Likewise, if the template is deleted, the notebook is unaffected.

Create a Notebook from Another Notebook

You can create a new notebook from an existing notebook by selecting Copy Notebook from the menu next to the name. Copying a notebook will include the value of any custom fields, where using a template does not preserve those values.

Give your new notebook a name, select a project (the project of the one you copied is the default), and click Yes, Copy Notebook to create the new one.

Manage Templates

Open the Template Dashboard by selecting Templates from the main menu. You can also select Manage > Templates from the Notebook Dashboard.

  • My Templates lists the templates you have created, whether they are shared with the team or not.
  • Team Templates lists templates created by other team members and shared with you.

Click the name of any template to open it. You can use the omnibox to search, filter, and sort longer lists of templates.

Delete Templates

To delete a template, select it on the template dashboard and click Delete. You may delete templates from which notebooks were created; those derived notebooks will be unaffected.

Related Topics




Configure Puppeteer


Puppeteer is an external web service that can be used to generate PDFs from Notebooks created with LabKey ELN. To use this service, you need to obtain the puppeteer premium module, and configure your LabKey Server as described in this topic.

Setup Puppeteer Service

puppeteer-service is a web service that allows for generation of assets (e.g. PDFs, screenshots) via Puppeteer. This service is built into a Docker image and served via Express.

Deployment

This service is deployable as a Docker container on either a Linux or OSX host. Docker is required to be installed on the host machine. You can retrieve the latest Docker image from Docker Hub using the following command:
docker pull labkeyteamcity/lk-puppeteer-service

If you would prefer to build the Docker image you can clone the LabKey puppeteer-service Git repository and follow the README's instructions for building an image:

git clone git@github.com:LabKey/puppeteer-service.git

This image can then be run in a container:

docker run -i --init --rm --cap-add=SYS_ADMIN -p 3031:3031 --name puppeteer-service labkeyteamcity/lk-puppeteer-service

A simple HTML view has been added to allow for interacting with the service. To see this view navigate to http://localhost:3031 to get familiar.

Windows Host Deploying this service on a Windows host is not supported nor tested.

Interface

POST to /pdf:
  • inputURL: The URL of the website to create a PDF or screenshot from.
  • apiKey: (Optional) If visiting a LabKey site that requires credentials you can specify an apiKey.
  • fileName: (Optional) Name of the file that is streamed back in the response. Defaults to generated.pdf.
  • printFormat: (Optional) Currently supports Letter and A4 page sizes. Defaults to Letter.
  • printOrientation: (Optional) Supports Portrait and Landscape orientations. Defaults to Portrait.

Configure Puppeteer Module

  • Select (Admin) > Site > Admin Console.
  • Under Configuration, click Puppeteer Service.
  • Set the properties following the guidance below.

Properties

Service Mode

The puppeteer module has two configuration modes for the puppeteer-service. These modes are:
  • remote: (Recommended) Remote mode configures LabKey Server to communicate with a remote instance of the puppeteer-service. The service is treated strictly as an external web service where the LabKey Server instance does not manage the service in any way.
  • docker: (Experimental) Docker mode leverages LabKey's docker module to configure and run a puppeteer-service container on the LabKey Server instance. This mode manages the lifecycle of the container (i.e. startup, running, shutdown) which shares computational resources with the LabKey server instance.
Remote mode is recommended for several reasons:
  1. Computational resources. Having the service running alongside LabKey Server, like it does in docker mode, can consume significant CPU and memory resources due to the overhead of the service as well as Docker.
  2. The remote puppeteer-service can be stood up once and shared by several LabKey Server instances (e.g. staging, production, etc).

Remote URL (Remote mode only)

The "Remote URL" property specifies the URL where the web service can be found. This is provided by whomever sets up the puppeteer-service instance.

Docker Image (Docker mode only)

Docker mode only. The Docker Image property specifies the name of the puppeteer-service image that is available on the LabKey Server instance. This image has to be downloaded via docker. See service deployment documentation for how to pull down an image.

Docker Port (Docker mode only)

The "Docker Port" property specifies what host port the service container should be bound to.

Startup Properties

All of the properties are also available as LabKey Server Bootstrap Properties. An example properties file (using Docker mode) would look something like:
puppeteer.enabled;startup=true
puppeteer.mode;startup=docker
puppeteer.docker.image;startup=lk-puppeteer-service:latest
puppeteer.docker.port;startup=3031
puppeteer.docker.remapLocalhost;startup=true
puppeteer.remote.url;startup=http://localhost:3031

Export Notebook as PDF

Once configured, you will see a button in your notebooks. Click and choose Export PDF.

Adjust settings including:

  • Format: Letter or A4.
  • Fit to Page: Check box to automatically scale down any contents wider than the page to fit the width of the PDF.
  • Orientation: Portrait or Landscape.
Click Export to export to PDF.

Related Topics




ELN: Frequently Asked Questions


Within LabKey Biologics, you can use data-integrated Notebooks for documenting your experiments. These electronic lab notebooks have direct access to 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 LabKey Biologics.

Who can see my Notebooks?

Every user with "Read" access to your Biologics project can also see all Notebooks created there.

What can I reference from a Notebook?

You can reference anything in your Biologics 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
The data archive will be compressed and stored in the database to allow future downloads. We will compute a SHA-2 cryptographic hash over the data archive and store it in the database. This allows us to verify that the contents of the data archive are exactly the same as the notebook that was signed and approved.

What happens to my Notebooks when I upgrade?

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

What are team templates?

Templates can give you a head start in creating a Notebook with a given format or containing boilerplate details. Team templates are shared with the team. You can also create personal templates that are not shared.

When you view the Templates Dashboard, all the templates you created are listed on the My Templates tab. Templates created by other users and shared with you are listed on the Team Templates tab.

Related Topics




Biologics: Freezer Management


Managing the contents of your freezers 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 freezers on the market. With LabKey Freezer Management, create an exact virtual match of your physical storage system, and then track where each sample can be found.
  • Match your digital storage to your physical storage.
  • Represent your exact physical freezer system, with shelves, racks, boxes, canes, bags, etc.
  • Track overall available freezer capacity helping you decide where to store new samples.
  • Answer questions about overall volume of samples by type and source; i.e. is there enough material from experiment A to complete the series of assays I want to run.
  • Find specific samples and know if they are available.
  • Move samples as needed and track each location change, including updating freeze/thaw counts and tracking amounts used.
  • Control which users can perform these actions using Freezer Storage Roles.

Topics

Learn more about creating, customizing, and using freezers in the Sample Manager documentation here:




Biologics: Shared Freezers


This topic is under construction for the 22.5 (May 2022) release of LabKey Biologics.

Multiple Biologics folders can share use of a single freezer by enabling the experimental feature "Subfolder data in LabKey Products". This supports creation of a nested set of Biologics subfolders within a single Biologics project.

Learn more in this topic: Biologics: Projects and Folders

Set Up Shared Freezer

To share a freezer, create it in the parent project, defining the properties and hierarchies as usual. It will then be visible in all subfolders of that project.

Users with the "Storage Editor" role in either the parent project or any subfolder will then be able to use the freezer to store and manage samples. Access to sample details is always dependent upon permissions in the container where the sample is defined.

In a shared freezer where a user has permission to see data from all subfolders using it, the user will see data from all containers as if all the samples were local. Using folder-specific naming prefixes can help users identify the source of samples.

Storage Occupied by Inaccessible Samples

In a shared freezer where a user does not have permission to read data from other containers, storage views will show a spaces as occupied, but instead of revealing any data about the sample, will show a icon. This means the space is occupied by a "restricted sample".

The same icon is shown when users move samples, ensuring both that spaces are never occupied by multiple samples and that data is only shared with authorized users.

Related Topics




Biologics Administration


This topic is under construction for the 22.5 (May 2022) release of LabKey Biologics. For the previous version of this documentation, click here.

Topics in this section will help Administrators understand and configure the Biologics application.

Biologics Users and Permissions

Administrators can manage user accounts and permission roles from within the application.

Select Administration from the avatar menu.

There are three tabs:

  • Users: See and manage the users with access to the application.
    • You can create, delete, deactivate, and reactivate users from this page.
  • Permissions: Grant (and revoke) roles for the users.
  • Settings: Control system settings including:
Learn more about managing users and roles in the companion topic for Sample Manager here:

Biologics Settings Tab

Select Administration from the avatar menu, then click the Settings tab to manage:




Biologics Admin: Grids, Detail Pages, and Entry Forms


Administrators can control which fields are shown in grids and detail views throughout LabKey Biologics. This includes views for Entities, Sample Types, Assays, and Issues/Workflow items. Admins can controls displays in the following ways:
  • adding and removing fields
  • re-labeling field headers
  • changing field order
  • sorting one or more columns
  • filtering one or more columns
Changing the default grid view will change how the grid appears in the Biologics application.

Adding additional named grids lets a user select them from a dropdown in the application.

Adding a grid view named BIOLOGICSDETAILS controls an entity's details page.

Grids

  • To control grid views, switch to the LabKey Server interface by selecting > LabKey Server > [Your Biologics Project Name].
  • Find the grid view you wish to change and click it. For example, to change the grid view for Protein Sequences, click ProtSequence under DataClasses.

On the ProtSequence DataClass select (Grid Views) > Customize Grid.

To add a field, select it on the Available Fields panel. Expand nodes with the icons. For example, below the Sequence > Mass field is being added.

To remove a field, click that field's X in the Selected Fields panel. For example, below the Avg. Mass field is being removed.

To change a display label for a field, click that field's (cog) in the Selected Fields panel. For example, below the label for the Organisms field is being changed to Species.

To change field order, drag-and-drop the fields in the Selected Fields panel.

When the changes have been made as desired, click Save in the lower right.

Save the grid as the Default grid view for this page if you want it to show to users by default. You can also save it as a named grid if you want to let the user select it by name.

Once the changes have been saved, they will be reflected in the Biologics application. Return to the application using the menu.

Details Pages

To control the fields on a details page, follow the same process as described above, except save the view using the name "BIOLOGICSDETAILS", capitalized and one word.

Once saved, the corresponding details view will reflect the changed UI.

Custom Grid Views

When administrators create custom grid views, these can be exposed to non-admin users in the Biologics user interface.

For details on creating custom grid views see Customize Grid Views. If you wish to expose a grid view to users, ensure that "Make this grid available to all users" is checked when saving the view.

When custom grid views are available to a user, they will be on the Grid Views menu to the right of the download button on summary grids. If no grid views are defined for that grid (other than the 'default', which is always defined), the menu will be shown in a grayed-out state.

Clicking Grid Views shows all of the views available to the current user, including the default view.

You can also select a grid view via the View option in the omnibox above the grid itself.

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:

  • Select > LabKey Server > [Your Biologics Project Name]
  • In the Data Classes list, click CellLine.
  • In the Data Class Properties panel, click Edit.
  • Click the Fields section to open it.
  • If there are already fields defined, you will see them. Otherwise, click Manually Define Fields.
  • Click Add Field, and specify the field's Name and Data Type.
    • Use the icon to expand the field and enter a Label if you don't want to use the name as the field label.
  • Click Save.
  • 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.

Related Topics




Biologics: Protect Sequence Fields


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

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 Settings from the user menu.
  • Under Protected Data Settings, 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: Protecting PHI Data

  • Not PHI
  • Limited PHI
  • Full PHI
  • Restricted PHI: the highest level of information to be protected. Sequences are protected at this level.
User permissions to see these levels are assigned in the LabKey Server interface:
  • Use the menu to select LabKey Server and your Biologics project.
  • Select > Folder > Permissions.
  • Assign the Restricted PHI Reader role to any user who should be able to read Sequences.
    • Note that this role is required to see Sequences, even for users with admin access to the Biologics application.
    • Learn more about setting permissions here: Configure Permissions
  • Save and Finish when permissions settings are complete.

Omit or Blank Protected Data

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

  • Select > LabKey Server > Your Biologics Folder.
  • Select > Folder > Management.
  • Click the Compliance tab.
  • Confirm that Require PHI roles to access PHI columns is checked.
  • Use the radio button to select either:
    • Blank the PHI column. (Default) The column is still shown in grid views and is available for SQL queries, but it will be empty.
    • Omit the PHI column. The column is completely unavailable to the user.

Learn more in this topic: Compliance: Configure PHI Data Handling

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 entity Data Classes 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 Data Class entities and Samples.

Note that PHI level restrictions apply to administrators as well. When Sequence protection is enabled, if the administrator is not also assigned the "Restricted PHI Reader" role, they will not be able to set PHI levels on other fields after this setting is enabled.

Protect Data Class Fields

When a field in an entity Data Class 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 Data Classes, such as registry entities including nucleotide and protein sequences, use the LabKey Server interface.

  • Use the menu to select LabKey Server and your Biologics project.
  • Click the name of the Data Class to edit, such as "NucSequence"
  • Click Edit.
  • In the Fields section, click to expand the desired field.
  • Click Advanced Settings.
  • Use the PHI Level dropdown to select the desired level.
  • Click Apply.
  • Click Save.
  • Return to the Biologics application.

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.

  • Click the name of your Sample Type on the main menu.
  • Select > Edit Sample Type Design.
  • In the Fields section, click to expand the desired field.
  • Click Advanced Settings.
  • Use the PHI Level dropdown to select the desired level.
  • Click Apply.
  • Click Save.

Related Topics




Biologics Admin: Charts and Reports


When administrators add charts or other visualizations in LabKey Server, they are surfaced above the corresponding data grid in the LabKey Biologics application. Reports are presented on a separate tab.

Charts

If charts are added to an assay run or result set, then they will be made available above that assay's data grid in the Biologics application. When charts are available, the Charts button above the data grid will be activated.

Add a Chart

Administrators can add visualizations using the standard mechanisms in LabKey Server.

  • To add a chart, first switch to LabKey Server by selecting > LabKey Server > [Name of your Biologics project].
  • Navigate to the appropriate table. (For example, if you wish to visualize the results for the Osmolarity assay, navigate to the Osmolarity assay, and then click View Results.)
  • To create the chart, click > Create Chart. Create and save the chart.
  • Go to the corresponding data grid in LabKey Biologics. (In this example, go the Osmolarity assay, and click the Results tab.)
  • Click the Charts button to see your visualization.
For details on creating charts in LabKey Server, see Visualizations.

Related Topics




Biologics Admin: Set Up Assays


Assay data is captured in LabKey Biologics 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. This topic describes how administrators create and manage the Assay Designs available in the system.

Overview

Each field has a name and data type, for example, the following Assay Design captures data from a Titration experiment.

SampleIDExpression RunSampleDateInjVolVialCal CurveIDDilutionResultIDMAb
2016_01_22-C3-12-B9-01ER-0052016-01-23302:A,19461881.0000478360.2000
2016_04_21-C7-73-B6-02ER-0052016-04-22302:B,19461881.0000478350.2300
2015_07_12-C5-39-B4-02ER-0042015-07-13302:C,19461881.0000478340.3000

The fields in an Assay Design are grouped into categories:

  • Run Fields: These are metadata fields that apply to one complete cycle of the experimental instrument or procedure. Possible run-level metadata fields would be: Operator (the lab technician who executed the experiment) or Instrument (the name of the lab instrument in which the experiment was performed).
  • Results (Data) Fields: These fields capture the main results of your experiment, for example, see above.
  • Other Categories: In some cases, there will be additional sets, such as Cell- or Analyte-level fields.

Assay Dashboard

Under Assays on the main menu, you will see a listing of designs already created in your system. Click Assays to open the dashboard.

The dashboard lists the assay design names and types, in a Grid by default. You can also select a Heatmap layout that will display the volume of runs imported for each assay over the past 12 months.

Note that when assay designs are created in the Biologics application, are scoped to the current folder. If your server includes any shared assays, you will also see them listed here. To create a shared or project scoped assay design, use the LabKey Server interface.

Click the name of an existing design to see the assay properties and a grid of runs imported using it. Use the to:

  • Export Design
  • Edit Design
  • Copy Design
  • Delete Design
  • View Audit History

Create a New Assay Design

To create a new assay design in LabKey Biologics, follow this process.

  • From the main menu, click Assays, then select Create > Assay Design.
  • Select the Assay Type. For most cases, leave the Standard Assay tab selected.
  • Click Choose Standard Assay.
  • In the Standard Assay Designer, enter Basic Properties:
    • Name field - this should reflect something about the nature of the assay and what is primarily being measured, for example, "Titer", "Immune Score", or "Cell Properties".
    • Active: When this box is unchecked, the design is archived and hidden in certain views.
    • Other fields are described in more detail in tooltips and in the topic: Assay Design Properties.
  • Click to open the Run Fields panel. Add run-level metadata fields as desired.
  • Click to open the Results Fields panel.
    • If there are no result fields defined yet, you will have the options to infer them from an example data spreadsheet (the supported formats are listed), import a prepared JSON file as for run fields, or click Manually Define Fields and add them individually.
  • Click Add Field to add new fields. Provide their Name and Data Type.
  • Keep adding fields until your data can be adequately captured.
  • To create a link between the assay data and the original samples, we recommend adding a SampleID field of type "lookup". See below for details.
  • Click Save.

Linking Assay Data to Samples

To link assay data to the originating samples, you can add a field with the data type Sample to your assay design.

  • In your Assay Design, add a field, typically in the Run or Results Fields section. This field can be of any name, such as SampleID or SpecimenID. Use whatever name best matches your result data.
  • In the Data Type column, choose the field type Sample.
  • Click the icon to expand field details.
  • Under Sample Options, select the desired Sample Type.
  • To link to all samples across any Sample Type, select All Samples from the "Sample lookup to" dropdown.
  • Click Save to confirm the changes.
To learn about connecting assay results to other kinds of entities, review this topic: Biologics Admin: Assay Integration

Review or Edit Assay Design

To review the details or edit a design, select it from the main menu and select > Edit Design.

You will see all the fields and properties set up when the design was created. If changes are needed, make them using the same method as for the creation of a new design. Click Finish Updating [Assay Name] to save changes.

Archive Assay Design

Assay Designs can be hidden from certain views by unchecking the Active checkbox in the Assay Properties. Archived, or inactive, designs are not shown on the main menu or available for new data entry through the Biologics application interface, but existing data is retained for reference. Note that you could still import new data for an archived assay in the LabKey Server interface if necessary.

Using the archive option can be helpful when a design evolves over time. Making the older versions "inactive" will ensure that users see the latest versions. An assay design may be reactivated at any time by returning to edit the design and checking the Active box again.

When viewing all assay data for a sample, both the active and archived assays will be shown if there is any data for that sample.

On the main Assays dashboard, you will be able to find inactive assays by switching to the All tab.

Related Topics




Biologics Admin: Assay Integration


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 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 an Entity type (such a Molecule), you can add other related fields to the assay design using Customize Grid. This must be done using the LabKey Server interface outside the Biologics application.

  • Select > LabKey Server > [Biologics Project Name].
  • Select (Admin) > Manage Assays.
  • Click the name of your assay, then click View Results.
  • Select > Customize Grid.
  • Use checkboxes to add fields, expanding nodes as needed. For example, the following screen shot shows how to add the Components field (which is a field of the Molecule Entity).
  • Save as the default view or a named grid view that is Shared with all users.
  • Select > LabKey Biologics > [Biologics Project Name] > Assays.
To see what Biologics assay users will see:
  • Click the name of your assay, then the Results tab.
  • The lookup fields and grid customizations will appear in the assay results grids, as show below. If you saved as a named grid instead of the default, you will be able to select that name from the Grid Views menu. When there is data for the Molecule column, any corresponding Components from the Molecule details will be shown.

Related Topics




Biologics Admin: Building from Source


The following instructions are for developers who want to build LabKey Biologics from source code.

General Development Set Up

Complete the general build instructions.

Add Biologics Modules

Get the biologics and related modules from github:

Gradle Set Up

Add the modules to the file settings.gradle in the project root to the end of the file:

include ":server:modules:biologics"
include ":server:modules:assayRequest"
include ":server:modules:assayReport"
include ":server:modules:recipe"
include ":server:modules:labbook"
include ":server:modules:trialServices"
include ":server:modules:sampleManagement"

In IntelliJ, hit the Gradle refresh button to have these new modules added to the IntelliJ project.

Build LabKey Server with Biologics

Build the server and verify the new modules are compiled:

> ./gradlew deployApp

Load Example Data

You can load Example data from two different sources.

In the Javascript console in your browser, call the following:

LABKEY.Ajax.request({
url: LABKEY.ActionURL.buildURL('biologics', 'loadSampleData.api'),
jsonData: {
id: 'eval'
}
});

The id can be either 'eval' or 'test' (for the data used in LabKey's automated tests).

Related Topics




Biologics Admin: URL Properties


The Biologics application offers a number of URL properties that can be used to direct the user to a specific part of the application. In these example URLs, we use the host "example.lkpoc.labkey.com" and a project named "Biologics Example". Substitute your actual server URL and path (everything before the "biologics-app.view?" portion of the URL.

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 programatically. Note that these examples assume various rowID to assay mappings that may be different in your implementation.

URL ending like thisCan be represented byResolves to...
Any Biologics URL#/.lastPageThe last page you were viewing
/assay-assayBegin.view?rowId=45#/assays/45#/assays/general/titer
/assay-assayResults.view?rowId=765#/assays/765#/assays/general/amino%20acids
/experiment-showDataClass.view?name=CellLine#/rd/dataclass/cellline#/registry/cellline
/experiment-showDataClass.view?name=Mixture#/rd/dataclass/mixture#/media/mixtures
/experiment-showData.view?rowId=3239#/rd/expdata/3239#/registry/molecularspecies/3239
/experiment-showMaterials.view?rowId=3087#/rd/samples/3087#/samples/expressionsystemsamples/3087
/list-grid.view?listId=18&pk=2#/q/lists/18/2#/q/lists/mixturetypes/2
/reports#/reportsReports dashboard
/assays#/assaysAssay dashboard

Related Topics




LabKey Biologics - Videos