Table of Contents

Introduction

Overview
Monoliths
Systems

Installation

Install

Workflows

General navigation
Create a plate set
Reformat 96 well plates into 384 well plates
Associate assay data with a plate set
Identify hits using an assay threshold
Generate liquid handling robot work lists
Rearray hits into a new plate set
Group two plate sets into a single plate set
Regroup plates within a plate set into a new plate set (split)
Import accession IDs

Utilities

Terminology
Simplifying assumptions

Tutorials

Tutorial 1 - Canonical workflow

Using the demonstration data, work through a cononical workflow. This tutorial is available as a video

Create a new plate set by reformating

Using the demonstration data, reformat Project 10, Plate Set 6, 10 96 well plates, into 384 well assay plates with a replication of 1. Navigate into Project 10 and select plate set 6:

Select reformat to be presented with the reformat form. The top panel provides information about the source plate set, and the bottom panels requests information on the design of the destination plate set. I will use sample replicates of 1 and target replicates of 4 i.e. all 4 quadrants of the 384 well plate coated with the same target. This requires that I define the layout as 1S4T.

Pressing Submit brings you to the confirmation page where you have the opportunity to select the target layout. I will get a new Plate Set #8, assuming no earlier modifications were made to the demo data. Navigate into PS-8 and note that there are 3 plates, 30-32, with 32 only half filled. I am ready to load data.

Apply barcode IDs to plates, Accession IDs to samples

Applying barcode and accession IDs is optional. The purpose of these identifiers is to allow you to associate LIMS*Nucleus data with data in other systems. Start by selecting the Plate Set of interest, PS-8 in this case, and follow the directions for importing accession ids and barcode ids. Use the following data:

ID type File
accession ps8-accessions.txt
barcode ps8-barcodes.txt

Note that empty wells in the third plate do not have an entry in the acessions file. A template for loading the accession IDs can be generated by exporting the underlying plate set data. The columns of interest are “Order” and “Well” which must be relabeled “plate” and “well”. Also include the accession as “accs.id”.

Load assay data.

Download the demonstration tab delimitted data set plates384x3_1S4T.txt to your local drive. The plate layout looks like:

and the response values look like:

This might be an ELISA assay showing a majority of responses less than 0.5. There is good reproducibility amongst the controls, with a good assay window. With the destination plate set highlighted, select Utilities/Import assay data:

Fill in the dialog, substituting the path name with the path to the file on your computer. Note that the import form provides a sample of what the import data should look like. Column order, spelling and capitalization are critical. After file selection the first few rows of data are displayed for confirmation:

I want hits automatically identified using a built in algorithm so I select the option mean +3SD in the algorithm dropdown so that all responses greater than the mean of the background wells + 3 standard deviation units are considered a hit. Because I am auto-identifiying hits, the add hit list name and description fields become active giving me the opportunity to name and describe the hit list. I did NOT select Top N as the selection algorithm so the number of desired hits field remains inactive:

Click import data. Not that the import button changes to ‘Loading…’. Do not reclick. Depending on the size of the data, import could take many seconds. Once complete you will be presented with the list of plates for the current plate set. Scroll down to see assaciated hit lists - HL-7 being the just created hit list:

View the Assay Run

Click on the assay run hyperlink AR-6, to view the data under default conditions - normalized with a threshold of mean of the negative controls plus 3 standard deviations. Controls are color coded:

Below the plot is a form for replotting under different conditions of normalization and thresholding. After replot, the tools menu allows for the viewing of hits above the selected threshold and the creation of a hit list if desired.

View the Hit List

To view a hit list, select the menu item under the tools icon. In the hit list view you can inspect the hits and are given the opportunity to save the list. Enter and name and description, and select ‘Add New Hit List’ from the tools menu:

Upon successful creation of the hit list you are presented with its parent assay run. Scroll to the bottom to see the newly created hit list:

Rearray

At this point you are ready to rearry your hits into a new plate set for secondary assay or further processing. Note that HL-7 contains 162 samples. Click on the ‘HL-7’ hyperlink to view the hit list. Scroll to the bottom to see the availability of hits in various plate sets:

In our simplistic demonstration data set, it is obvious that the parental samples for our assay plate set are in plate set 6. In real life processing, samples may get distributed across many plate sets. Use the type and count fields to help determine an appropriate source of samples for rearray. Assay plates are typically transient and not a source of material for rearraying. You must establish type naming conventions for your plate set, for example archive plates or master/daughter/rearry plates contain samples while assay plates are transient. In the demo data PS-6 is labeled “master”, which helps identify a plate that contains the parent samples. Assay plates are typically transient and not a source for sample recovery.

The count field is to confirm that a particular plate set contains (or not) all the hits of interest. If no single plate set contains all hits, you may have to group plate sets.

Select the plate set that will serve as the rearry source and select “Rearry” using the tools button. This will initiate the production of a new plate set that will contain hits only:

Provide the requested information and press “Submit”. You will then have the opportunity to select the layout of controls. The number of plates required will be automatically calculated and hits will be distributed in numerical order by column into the plates. Since this is a rearray plate, and not an assay plate, the target is auto-assigned to DefaultQuadruplicates, which is inconsequential. To achieve the physical rearry in the lab a worklist is generated and associated with the plate set. Indication that a plate set was generated by a worklist is the presence of the worklist ID in the “worklist” column in the plate set view. Only plate sets generated by a rearray have an integer in the “worklist” column. The worklist is permanently stored in the database and can be recalled by selecting the plate set and using the tools icon select ‘Worklist’.

The worklist will be displayed:

The worklist can be exported to e.g. Microsoft Excel or LibreOffice Calc, depending on what your computer has associated with the .CSV extension:

This worklist can be used with a liquid handling robot such as a Beckman Biomek, to perform the physical rearry.

Tutorial 2 is a repeat of the canonical workflow, this time using an assay plate layout that allows for duplicate samples.

Tutorials

Tutorial 3, target layout definition

In tutorial4 we will run through the canonical workflow using duplicate targets. We could use the built in defaults target1, target2 etc., but we will assume you have a companion database that holds target specific information, and we wish to merge our assay data with the target information.

Assume we are screening transferrin receptor (CD71) antibodies against the receptor and a negative control - BSA. First we need to register the targets in our system. Use the target import file defined here. Select the menu item Targets/All Targets, (Note: if you are using the cloud demo database these targets have already been imported for you.) and select the ‘Bulk Target Upload’ option under the tools menu. Indicate the location of the downloaded targets.txt and import. The targets are now registered within project 10 and available in the targets dropdown.

Navigate into project 10 and select Targets/All Target Layouts. Select ‘Add Target Layout’ under the tools menu. Fill in Name and description and select Replication = 2. Select huCD71 for quads 1,3 (noting that target duplicates are always in the same column, sample duplicates in the same row). Select BSA for quads 2,4.

The layout will now be available during plate set creation or reformating within project 10:

Note that “TLY-4”” is only available in project 10 and only when target layout is set to “2”, which is only available when sample replication is set to 2 or 4.

Tutorial 4 will use this target layout with a new plate set created by reformatting.

Tutorials

Tutorial 4 - canonical workflow with target replicates

Tutorial 1 covers in detail steps that are glossed over in this tutorial. Tutorial 3 covers creation of the target layout.

Looking at available sample layouts there are 2 that offer replication - 2S4T and 4S2T:

2S4T: Entire plate coated with the same target, samples in duplicate. Note that sample replicates are in the same row. (see tutorial 2 )

4S2T: Each sample tested in duplicate on 2 targets. Note that target replicates are in the same column.

Following tutorial 1 I will rearray the 10 plates of PS-6 into a new plate set applying the 4S2T sample layout. Ten 96 well plates in quadruplicate will requires ten 384 well plates, one 96 well plate in all 4 quadrants of a 384 well plate:

I will use the target layout created in tutorial 3 as the target layout, providing me with duplicate assay results for each sample.

Use the data file plates384x10_4S2T.txt which contains demonstration data for ten 384 well plates. The data has been generated such that replicates are one above the other in the same column and are +/-10% of each other. In the graph below replicates for one plate are color coded and appear at the same X value:

Looking at the response trellised by plate and colored by sample type:

Associate the data with the plate set. Note that plate set, hit list, and assay run ids may differ from what is shown if you worked through all the tutorials:

Select the file you downloaded:

Provide requested information and import data:

View the assay run and hit list under PS-12

Navigate into HL-9 and view hit availability. Note that the hit list has 306 hits. PS-6 is the master plate that provides the hits. The discrepancy is discussed below.

Responses are plotted in decreasing order with controls color coded. Not that if you select normalized response with a hit threshold set to mean(background)+/-3SD, 306 hits will be identified. The hit list could have been created here, but was already auto-generated on import.

View the new plateset PS-13. Note the associated worklist because this plate set was created by a rearray action.

Note that the hit list contains 306 hits but the parental plate set PS-6 only contains 276 of the samples designated as clones. Seven of our samples have scored as hits on both target 1 and 2. This can be seen in the exported worklist below. For example sample SPL-2829 scored on both targets, but will be rearrayed only once. To characterize which samples score on which target, you must export the results and analyze outside LIMS*Nucleus.

Processed data can be exported for further analysis. While viewing an assay run, use the ‘View all data’ to generate a table that can be exported to Excel:

Results are exported into whatever application you have associated with .csv files:

Note that due to the use of defined targets, the target annotation appears in the worksheet. For targets both the name and accession are available. Sample accessions were not imported and so don’t appear. Compare to an analysis where the default target annotation is used, such as PRJ-1, AR-1. The generic target label “Target1” is used, without any associated accession:

Developer

Urbit

Purpose

Ease your organization into Urbit by using the Urbit ID system to validate users. Use the Landscape viewer to distribute software - in this case a simple hyperlink to an internally developed web app. No hoon coding required. The web app must be modified to accept white listed Urbit IDs.

Prepare Linux

The following is a modification of the hello app found on developers.urbit.org. I am starting with a new instance of Debian 11 on AWS. Note that some of the commands below will need to be modified with your AWS credentials, configuration. This video walks through the process.

Update, install some utilities and create a swap space:

1
2
3
4
5
6
7
sudo apt-get update
sudo apt-get install git

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

edit fstab:

1
sudo nano /etc/fstab

add the following line:

/etc/fstab
1
/swapfile swap swap defaults 0 0

Prepare new desk contents

Clone the required desks and merge them into your project desk OR git clone the limsn project and apply modifications. Note that this process slightly differs from developers.urbit.org which is out of date:

1
2
3
4
5
6
7
8
9
10
11
12
13
projects$ git clone https://github.com/urbit/urbit urbit-git
projects$ git clone https://github.com/tloncorp/landscape

projects$ mkdir urblimsn

cp -rfL /home/mbc/projects/urbit-git/pkg/base-dev/* /home/mbc/projects/urblimsn
cp -rfL /home/mbc/projects/landscape/desk-dev/* /home/mbc/projects/urblimsn

projects/urblimsn$ echo "[%zuse 415]" > sys.kelvin
projects/urblimsn$ echo "~zod" > desk.ship

projects/urblimsn$ nano desk.docket-0

Modify the contents of desk.docket-0 to suit your needs:

desk.docket-0
1
2
3
4
5
6
7
8
9
10
11
:~  title+'LIMS*Nucleus'
    info+'A link to LIMS*Nucleus Web App.'
    color+0x81.88c9
    image+'https://github.com/mbcladwell/limsn/raw/main/limsn/pub/img/las-walpha-small.png'
    base+'limsn'
    glob-ames+[~zod 0v0]
    version+[0 0 1]
    website+'https://github.com/mbcladwell/urblimsn'
    license+'MIT'
==

The merged desks, auxilliary files and glob can be cloned, see below.

Prepare fake zod

Start up a fake zod, create and mount a new desk, delete the desk and git clone its replacement:

1
2
3
4
5
6
curl -L https://urbit.org/install/linux-x86_64/latest | tar xzk --transform='s/.*/urbit/g' && ./urbit
./urbit -F zod
~zod:dojo>|new-desk %limsn
~zod:dojo>|mount %limsn

Ctrl-d   (to kill zod)

cd into zod and delete the new desk. git clone its replacement. The cloned directory contains the merged dev desks, desk.ship etc. as well as a glob:

1
2
3
4
cd ./zod
zod$ rm -rf ./limsn
zod$ git clone https://github.com/mbcladwell/urblimsn.git limsn
cd ..

Get the glob out of the desk or the desk will not compile:

1
$ mv ./zod/limsn/glob .

On local machine transfer glob to local machine:

1
scp -r -i labsolns.pem admin@ec2-3-145-214-48.us-east-2.compute.amazonaws.com:./glob .

On zod:

1
2
~zod:dojo>|commit %limsn
~zod:dojo>|install our %limsn

Assuming fake zod is on your local machine you can point your browser to localhost:8080 and see landscape with a new LIMS*Nucleus tile with spinner indicating “loading”. For AWS I use my temporary IP: http://3.142.185.219:8080.

To complete the install you must upload the glob. First modify index.html to suit your needs:

index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
<!DOCTYPE html>
<html>
  <head>
     <meta charset="UTF-8" />
    <script src="https://unpkg.com/@urbit/http-api"></script>
     <script src="/session.js"></script>
  </head>
  <body>
  </body>
  <script>
     location.replace('http://3.145.214.48:3000/urbit?name=' + window.ship);
  </script>
</html>

The javascript helper scripts are discussed in the http api guide. Note the ‘window.ship’ variable which provides the ship name (‘zod’ in this example) for appending to your web app’s urbit controller. In LIMS*Nucleus, urbit ids must be white listed in the ‘person’ table:

1
2
3
4
5
6
7
8
9
10
11
lndb=> select * from person;
 id |  lnuser  |      passwd      |       salt       |       email       | usergroup 
----+----------+------------------+------------------+-------------------+-----------
  1 | ln_admin | 1d52114553ae31b3 | a39b69e5fd79854b | info@labsolns.com | admin
  2 | ln_user  | ca6468f6ff4a82e6 | e999f4c34635f943 |                   | user
  3 | demo     | 97f8647f1067346d | 55ecb01c50cb1ae1 |                   | user
  7 | zod      | 1f4973fea4b98a05 | 616c7e5555c1df62 |                   | admin
  8 | nus      | 9a58637cbeab8afc | 8e4d24fcb45af66c |                   | user
(5 rows)

lndb=>

Note the the urbit ID password hashes are a hash of the salt only as the password is blank. Urbit users come to the app prevalidated.

To upload the glob navigate to localhost:8080/docket/upload, select the limsn desk, press browse and select the glob directory and press the “glob!” button. Returning to zod you should now see:

Click on the LIMS*Nucleus tile and you will be redirected to the web app and logged in.

To allow zod to distribute this link, at the dojo:

1
~zod:dojo>:treaty|publish %limsn

Now if I create a fake ~nus on the same instance of AWS but broadcast on port 8081, I can query ~zod on 8080 for software offered. We can piggyback on the Urbit desk distribution mechanism to distribute software - though in this example we are simply distributing a hyperlink allowing redirection:

Videos

Videos

LIMS*Nucleus

Overview and functionality

Navigating the LIMS*Nucleus Interface

Tutorial 1

Sample and Target Replication

Designing plate layouts

LIMS*Nucleus installation on AWS EC2

LIMS*Nucleus installation using a Guix pack

Install the LIMS*Nucleus PostgreSQL database on AWS Relational Database Service (RDS)

Use a Guix Pack to install LIMS*Nucleus on Windows 11/WSL2

Verify users and assign permissions using Urbit IDs

Guix

Modular LIMS Development with Guix

Guix package a Guile module

Guix package a Debian archive file

Set up a Guix channel

Guix package an R library

Guix package a Shiny app

Run multiple Guix packaged Shiny apps on a shared Shiny server

Contribute a package recipe to Guix nonguix

How Guix enables reproducible computing

License

This file is part of LIMS*Nucleus.

LIMS*Nucleus can not be copied and/or distributed without the express permission of Laboratory Automation Solutions

This project is not open source, but source code is available to licensees.
You are not allowed to redistribute this project with “enhancements” i.e. fork.
You may modify this project to suit your needs, but must retain the modified code within your organization.
You cannot commercialize this project.

A perpetual license ($5000 USD) provides:

  • all future upgrades
  • bug fixes
  • support
  • source code

Register here

15% discount for customers who pay with Bitcoin/Litecoin

Free license to academics who register with an .edu email

For more information contact: info@labsolns.com