Unchained Labs, Lunatic Configuration Guide

To provide details about the necessary steps to implement the Unchained Labs Lunatic data connector for use with the Benchling Connect platform.

Introduction

The Benchling Connect, Unchained Labs Lunatic data connector is a component used in the context of the Benchling Connect platform to parse data from Unchained Labs Lunatic Plate Readers to an Allotrope Simple Model (ASM) and make that data available within the Benchling UI in the context of a Run.

The Benchling Connect, Lunatic data connector is a ‘file-based’ based data connector, meaning that it processes .csv or .xlsx file exports generated by the Lunatic & Stunner Analysis application. The data within the file export is then accessed by Benchling Connect through the use of a ‘watched’ file directory on the local computer hosting a Benchling Gateway, which has been configured via a Connection from within Benchling.

In order to successfully implement the Unchained Labs Lunatic data connector for use with the Benchling platform, there are multiple steps that need to be followed across both the Unchained Labs Lunatic and Benchling user interfaces. 

This guide details the steps to be taken in both applications in order to configure the integration. 

Steps within Unchained Labs Lunatic Software

Lunatic and Stunner software utilities

When using the Unchained Labs Lunatic instrument, the user utilizes two companion applications installed on the computer connected to the instrument, Lunatic & Stunner Client software for acquiring data, and Lunatic & Stunner Analysis software for reviewing the results. While these applications are used in conjunction with two instrument models, the Lunatic and the Stunner, the Benchling Connect, Lunatic data connector currently only supports exports from the Lunatic instrument.     

Data Acquisition Set Up

From within the Lunatic & Stunner Client software, users will have to set up their assays to either Protein or Nucleic Acids modes.

Next the user can select from a menu of pre-configured acquisition settings. The Benchling Connect, Lunatic data connector currently supports processing data from the following assays only: dsDNA (Turbidity), ssDNA (Turbidity), RNA (Turbidity), and Protein (Turbidity).

The plate map utility can be used to annotate the samples being measured. At this point, It is possible to import a plate map as a .csv file using an Input File generated by the Run in Benchling if the file follows the template specified in the Lunatic Software User Guide. Specifically, this file is expected to have the following column headers:

• B/S/R - where each row has a “B”, “S” or “R” to denote Blank, Sample, or Reference
• Plate ID
• Plate Position - well position in alphanumeric format (e.g. A1)
• Sample name
• Sample Group
• Source Plate ID
• Source Position

Configuring Data Export

Following the acquisition of data using the instrument, the Lunatic & Stunner Client software will produce a .bin file which will be automatically opened within the Lunatic & Stunner Analysis software. It is also possible to import the .bin files from previous Lunatic experiments into the Lunatic & Stunner Analysis software application. The user should navigate to the  file of interest to open the report settings

From the Report Settings tab the user may add columns to the export file by dragging items from the left column to the right column, however, the following are several required columns which must be included in the file export:

• Plate ID
• Plate Position
• Sample Name
• Sample Group
• Application
• Date
• Time
• Instrument ID
• Absorbance Measurement (e.g. A260)

To ensure that the required columns are always included, it is possible to save the report layout for future use. 

Once the columns are configured, the user can export the file as a .csv or .xlsx file by clicking the Save Report button in the right hand side bar.

The user should save the export file (.csv or .xlsx) in the same folder used when configuring the Connection within Benchling.

File Extension Formatting Differences

The Unchained Labs, Lunatic Connector supports multiple file extensions (.xlsx and .csv) exported from the Lunatic & Stunner Analysis software.

The two file extensions, however, appear in two differing formats whereby the .xslx contains an additional header above the tabular results (see image below).

The Lunatic Connector expects the .xlsx to start with a single line Report at the top, then a single line with Table above the tabular results data.

The .csv file will only contain the tabular results data without an additional header (see image below).

Steps within Benchling

From within Benchling, a user must:

1. Enable the Unchained Lunatic data connector on the tenant [internal admin console]

2. Configure a Unchained Lunatic Connection

3. Create a Result schema to structure the data to be recorded

4. Configure a Run schema to accept data from Unchained Lunatic and records Results

For steps 1 and 2, please reference the Benchling Connect Installation Guide for details related to creating and installing a Gateway and configuring a Connection.

Data returned by Unchained Lunatic Data Connector

The Benchling Connect - Lunatic data connector uses the Allotrope Simple Model (ASM) to structure the information parsed from the Unchained Lunatic file export. The data is processed in a two step process; step one from Unchained Lunatic export to the .json based ASM, and step two from the ASM .json to a .csv files available for ingest to Benchling.

These data are structured using the Allotrope Plate Reader ASM data model (BENCHLING/2023/09). Details about the ASM schema can be found here:

https://github.com/Benchling-Open-Source/allotropy/tree/main/src/allotropy/allotrope/schemas/adm

The data connector then converts the ASM to a well file .csv file, such that each row of the file represents a well of the plate - along with metadata about the experiment

For the Unchained Lunatic, the well file will typically contain the following columns (if available within the data):

• Device Identifier
• Model Number
• Product Manufacturer
• Software Name
• ASM Converter Name
• ASM Converter Version
• Container Type
• Software Version
• Measurement Identifier
• Measurement Time
• Sample Identifier 
• Analytical Method Identifier - this refers to the application used (e.g. dsDNA Turbidity)
• Well Plate identifier - this refers to the plate name
• Location identifier - this refers to the well position
• Number of Wells
• Device Type 
• Detection Type - this will refer to Absorbance
• Detector Wavelength Setting 
  • In cases of experiments measured at multiple wavelengths, this column will be annotated with a number indicating the read.
• Absorbance - this column will be annotated with the unit e.g absorbance_mAU
  • In cases of experiments measured at multiple wavelengths, the column will be annotated with a number indicating the read

The well file will also include additional columns related to calculations performed on the measurements from each well, examples will include:

• A260 Concentration 
• Background (A260)
• A260/A230
• A260/A280

Sample files can be found here.

Configure Run Schema to employ Unchained Labs, Lunatic Connection

The Run schema can be created from the menu under Feature Settings.

As part of the Run schema creation, the user should specify 'Unchained Labs, Lunatic' as the Connection Schema.

Configure the Output File Processor

For details on configuring the Output File Processor within the Run schema, please refer to these articles.

• Configure the Output File Config of a Benchling Connect Run
• Configure the Output File Processor to Create New Entities
• Configure the Output File Processor to Capture Results

Unchained Lunatic Data Connector Requirements

* This is the version of Lunatic & Stunner Analysis software with which the data connector has been developed and tested. The data connector may work with other versions of Lunatic & Stunner Analysis software, but that must be verified by the user.

Revision History

2024/01/30

Initial Version

2024/08/30

Update supported file extensions to include .XLSX files

2024/09/03

Update link to referenced schemas in Github 

2024/09/10

Additional context and images added to file extension formatting differences, .xlsx/.csv exports

2024/09/18

Added Github testdata link

2024/09/20

Update list of returned column headers from well data file