If your experiment uses plate-based data, but does not fit one of our predefined types, you can define a
General assay design and configure it to import plate data and metadata alongside other run and result fields. A plate template defines the well layout and attributes of different well groups. In concert with a JSON file of plate metadata, plate data is interpreted and included in imported assay results.
A single general assay design can be used with multiple plate templates. A user importing data a selects the plate template to use and also uploads the corresponding plate metadata JSON file. The assay design domain is updated when necessary to include the superset of fields from all templates in use.
Scoping and Permissions
Scoping and Locations
Before defining your assay designs and plate templates, determine where you want them to be available for users. Assay designs and templates can be:
- folder-scoped: Defined in a folder and available only in the local folder.
- project-scoped: Defined in a project and available in the project itself as well as all folders within it.
- site-scoped: Defined in the Shared folder and available anywhere on the site.
For example, if you want everyone using your site to be able to use an assay design and 3 possible plate template layouts, all should be defined in the Shared project.
Permissions
During the import process, if the plate metadata includes fields not already included in the assay design, the design will be
dynamically updated to add necessary fields. Note that this means that only administrators or users with the "Assay Designer" role can upload plate data that is not already present in the design. If a user without this access attempts to import a run which would change the plate domain, the import will fail.
If an administrator wants to ensure that users without this access can use a given plate template, they should upload a first run using it to ensure the plate data fields are created correctly.
Define Plate Template(s)
There are two blank templates that can be used to create General plate-based assay templates: One for an 96 well plate and another for a 384 well plate. To create a plate template:
Each offers a
layer (tab) for both
Control and
Sample wells. Each layer has distinct sets of well groups, assigned a color and shown beneath the grid. Select a group and click or drag to 'paint' wells with it, indicating where that group is located on the plate.
Using one of these blanks, customize your template(s) using the instructions in this topic:
The user will select the plate template at the time of upload, and also upload a corresponding
metadata file. It is good practice to name your templates in a way that users can identify the matching json.
Admins can define multiple templates to capture data from different plate layouts and use them in the same assay design. Each template you create needs a unique name in the context in which it will be used.
Create Plate Metadata JSON File
The metadata for plate layouts is provided in a specially formatted JSON file.
When you are importing data you have the option to
Download Example Metadata File that looks like the following. Use it as a starting place for creating the metadata file(s) you need.
-- this is not valid JSON but is an example of the required structure
-- of the plate metadata file contents (removing the comments will make it valid)
{
-- each layer in the plate template can be matched by name
-- with a JSON object, in this example both control and specimen
-- are defined in the plate template that will be selected in
-- the run properties during import
"control" : {
-- each well group in the layer can be matched by name
-- with a JSON object, in this case POSITIVE and NEGATIVE well group names
"POSITIVE" : {"dilution": 0.5},
"NEGATIVE" : {"dilution": 5.0}
},
"sample" : {
-- arbitrary properties can be associated with the
-- well group, these will be imported into the results grid
-- as columns for example : dilution and ID fields
"SA01" : {"dilution": 1.0, "ID" : 111},
"SA02" : {"dilution": 2.0, "ID" : 222},
"SA03" : {"dilution": 3.0, "ID" : 333},
"SA04" : {"dilution": 4.0, "ID" : 444}
}
}
Some terminology to help with interpreting metadata files:
- layer: Each tab in the plate template editor (Control and Sample in the general plate templates) corresponds to a layer that is shown as a named grouping of well definitions in the above.
- grouping: The well group names on each tab are repeated in the metadata file as JSON objects. Shown above, Positive, Negative, SA01, etc. are all well group names.
- properties: Plate data properties are identified in the JSON object as name:value pairs. Shown above, "Dilution" and "ID" are both properties.
Design General Plate Based Assay
When you define a general assay design to use plate information you
do not include the fields that will be provided by plate information. Include batch, run, and results fields as for
general assays that do not use plates. The functionality of requesting and interpreting plate data is triggered by a single checkbox during assay design creation:
- From the Assay List, click New Assay Design.
- Select the General assay type and choose the location where you want to define the assay.
- Name the assay design (required).
- Check the Plate Metadata box.
- Continue to define the rest of the assay as usual. You will define Batch, Run, and Result Fields.
- You will not define any fields that will be provided with the plate data.
- Click Save
Use General Plate Based Assay
When a user imports data using a Plate-Based General assay, during entry of
Run Properties, they provide a run file, plate template, and metadata JSON file.
The
first time a given plate template and metadata JSON file are used, the assay design will be updated to add new fields to hold the plate metadata. This means that the first time importer must be an administrator or have the "Assay Designer" role, otherwise the import will fail.
Subsequent imports using the
same template and metadata can be performed by users without this permission. Subsequent imports using
new templates or metadata that add fields to the plate data domain must also be performed by an administrator or assay designer.
After uploading the first run using the new assay design, the admin or assay designer can reopen the design to see the new fields that have been added by the upload of plate data and metadata.
- Click the assay name in the Assay List.
- Select Manage assay design > Edit assay design.
- Open the Run Fields section to see the PlateTemplate lookup field.
- Open the Results Fields section to see the WellLocation text field.
- Scroll down and open the PlateDataDomain added during upload. The fields included depend on the information in the metadata JSON file. This image corresponds to the sample json shown above.
Subsequent data imports that use the
same template and metadata will not add new fields, and can thus be performed by users with upload access. If you need to change the plate template, plate metadata, or add a second plate template that includes additional fields or properties, an administrator or assay designer must perform the first import of run data with the new plate metadata in order to dynamically update the assay design.
View Result and Plate Data
Imported assay data will include a combination of fields from both the assay design (Run/Batch/Results Fields) and plate data. Use the
(Grid views) > Customize grid to adjust the fields shown.
Related Topics
