Imaging

CODEX / CODEX2

Related files:

This schema is for CO-Detection by indEXing (CODEX). CODEX uploads require metadata on the antibodies used in the assay to be provided in an Antibodies TSV. For CODEX, in that TSV, the channel_id is a cycle#/channel# combination linked to a given image file (of the form Cycle[0-9]_CH[0-9]). Each TIF file in a CODEX dataset contains image data captured from a single channel in a single cycle, identified and connected to the channel_id by its location in the upload directory (of the form src_*/cyc*_reg*_*/*_*_Z*_CH*.tif). For an example of a CODEX dataset & directory, see this example CODEX dataset and click the Globus link. The other fields function the same way for all assays using antibodies. For more information, see the Antibodies TSV documentation.

Metadata schema

Version 1 (use this one)
Shared by all types

version
description
donor_id
tissue_id
execution_datetime
protocols_io_doi
operator
operator_email
pi
pi_email
assay_category
assay_type
analyte_class
is_targeted
acquisition_instrument_vendor
acquisition_instrument_model

Unique to this type

resolution_x_value
resolution_x_unit
resolution_y_value
resolution_y_unit
resolution_z_value
resolution_z_unit
preparation_instrument_vendor
preparation_instrument_model
number_of_antibodies
number_of_channels
number_of_cycles
section_prep_protocols_io_doi
reagent_prep_protocols_io_doi
antibodies_path
contributors_path
data_path

Shared by all types

version

Version of the schema to use when validating this metadata.

constraint value
enum 1
required True

description

Free-text description of this assay.

constraint value
required True

donor_id

HuBMAP Display ID of the donor of the assayed tissue. Example: ABC123.

constraint value
pattern (regular expression) [A-Z]+[0-9]+
required True

tissue_id

HuBMAP Display ID of the assayed tissue. Example: ABC123-BL-1-2-3_456.

constraint value
pattern (regular expression) (([A-Z]+[0-9]+)-[A-Z]{2}\d*(-\d+)+(_\d+)?)(,([A-Z]+[0-9]+)-[A-Z]{2}\d*(-\d+)+(_\d+)?)*
required True

execution_datetime

Start date and time of assay, typically a date-time stamped folder generated by the acquisition instrument. YYYY-MM-DD hh:mm, where YYYY is the year, MM is the month with leading 0s, and DD is the day with leading 0s, hh is the hour with leading zeros, mm are the minutes with leading zeros.

constraint value
type datetime
format %Y-%m-%d %H:%M
required True

protocols_io_doi

DOI for protocols.io referring to the protocol for this assay.

constraint value
required True
pattern (regular expression) 10\.17504/.*
url prefix: https://dx.doi.org/

operator

Name of the person responsible for executing the assay.

constraint value
required True

operator_email

Email address for the operator.

constraint value
format email
required True

pi

Name of the principal investigator responsible for the data.

constraint value
required True

pi_email

Email address for the principal investigator.

constraint value
format email
required True

assay_category

Each assay is placed into one of the following 4 general categories: generation of images of microscopic entities, identification & quantitation of molecules by mass spectrometry, imaging mass spectrometry, and determination of nucleotide sequence.

constraint value
enum imaging
required True

assay_type

The specific type of assay being executed.

constraint value
enum CODEX or CODEX2
required True

analyte_class

Analytes are the target molecules being measured with the assay.

constraint value
enum protein
required True

is_targeted

Specifies whether or not a specific molecule(s) is/are targeted for detection/measurement by the assay.

constraint value
type boolean
required True

acquisition_instrument_vendor

An acquisition_instrument is the device that contains the signal detection hardware and signal processing software. Assays generate signals such as light of various intensities or color or signals representing molecular mass.

constraint value
enum Keyence or Zeiss
required True

acquisition_instrument_model

Manufacturers of an acquisition instrument may offer various versions (models) of that instrument with different features or sensitivities. Differences in features or sensitivities may be relevant to processing or interpretation of the data.

constraint value
enum BZ-X800, BZ-X710, or Axio Observer Z1
required True

Unique to this type

resolution_x_value

The width of a pixel. (Akoya pixel is 377nm square)

constraint value
type number
required True

resolution_x_unit

The unit of measurement of width of a pixel.(nm) Leave blank if not applicable.

constraint value
enum mm, um, or nm
required False
required if resolution_x_value present

resolution_y_value

The height of a pixel. (Akoya pixel is 377nm square)

constraint value
type number
required True

resolution_y_unit

The unit of measurement of height of a pixel. (nm) Leave blank if not applicable.

constraint value
enum mm, um, or nm
required False
required if resolution_y_value present

resolution_z_value

Optional if assay does not have multiple z-levels. Note that this is resolution within a given sample: z-pitch (resolution_z_value) is the increment distance between image slices (for Akoya, z-pitch=1.5um) ie. the microscope stage is moved up or down in increments of 1.5um to capture images of several focal planes. The best one will be used & the rest discarded. The thickness of the sample itself is sample metadata. Leave blank if not applicable.

constraint value
type number
required False

resolution_z_unit

The unit of incremental distance between image slices. Leave blank if not applicable.

constraint value
enum mm, um, or nm
required False
required if resolution_z_value present

preparation_instrument_vendor

The manufacturer of the instrument used to prepare the sample for the assay.

constraint value
enum CODEX
required True

preparation_instrument_model

The model number/name of the instrument used to prepare the sample for the assay.

constraint value
enum version 1 robot or prototype robot - Stanford/Nolan Lab
required True

number_of_antibodies

Number of antibodies.

constraint value
type integer
required True

number_of_channels

Number of fluorescent channels imaged during each cycle.

constraint value
type integer
required True

number_of_cycles

Number of cycles of 1. oligo application, 2. fluor application, 3. washes.

constraint value
type integer
required True

section_prep_protocols_io_doi

DOI for protocols.io referring to the protocol for preparing tissue sections for the assay.

constraint value
required True
pattern (regular expression) 10\.17504/.*
url prefix: https://dx.doi.org/

reagent_prep_protocols_io_doi

DOI for protocols.io referring to the protocol for preparing reagents for the assay.

constraint value
required True
pattern (regular expression) 10\.17504/.*
url prefix: https://dx.doi.org/

antibodies_path

Relative path to file with antibody information for this dataset.

constraint value
required True

contributors_path

Relative path to file with ORCID IDs for contributors for this dataset.

constraint value
required True

data_path

Relative path to file or directory with instrument data. Downstream processing will depend on filename extension conventions.

constraint value
required True
Version 0

Shared by all types

donor_id

HuBMAP Display ID of the donor of the assayed tissue. Example: ABC123.

constraint value
pattern (regular expression) [A-Z]+[0-9]+
required True

tissue_id

HuBMAP Display ID of the assayed tissue. Example: ABC123-BL-1-2-3_456.

constraint value
pattern (regular expression) ([A-Z]+[0-9]+)-[A-Z]{2}\d*(-\d+)+(_\d+)?
required True

execution_datetime

Start date and time of assay, typically a date-time stamped folder generated by the acquisition instrument. YYYY-MM-DD hh:mm, where YYYY is the year, MM is the month with leading 0s, and DD is the day with leading 0s, hh is the hour with leading zeros, mm are the minutes with leading zeros.

constraint value
type datetime
format %Y-%m-%d %H:%M
required True

protocols_io_doi

DOI for protocols.io referring to the protocol for this assay.

constraint value
required True
pattern (regular expression) 10\.17504/.*
url prefix: https://dx.doi.org/

operator

Name of the person responsible for executing the assay.

constraint value
required True

operator_email

Email address for the operator.

constraint value
format email
required True

pi

Name of the principal investigator responsible for the data.

constraint value
required True

pi_email

Email address for the principal investigator.

constraint value
format email
required True

assay_category

Each assay is placed into one of the following 4 general categories: generation of images of microscopic entities, identification & quantitation of molecules by mass spectrometry, imaging mass spectrometry, and determination of nucleotide sequence.

constraint value
enum imaging
required True

assay_type

The specific type of assay being executed.

constraint value
enum CODEX
required True

analyte_class

Analytes are the target molecules being measured with the assay.

constraint value
enum protein
required True

is_targeted

Specifies whether or not a specific molecule(s) is/are targeted for detection/measurement by the assay.

constraint value
type boolean
required True

acquisition_instrument_vendor

An acquisition_instrument is the device that contains the signal detection hardware and signal processing software. Assays generate signals such as light of various intensities or color or signals representing molecular mass.

constraint value
enum Keyence or Zeiss
required True

acquisition_instrument_model

Manufacturers of an acquisition instrument may offer various versions (models) of that instrument with different features or sensitivities. Differences in features or sensitivities may be relevant to processing or interpretation of the data.

constraint value
enum BZ-X800, BZ-X710, or Axio Observer Z1
required True

Unique to this type

resolution_x_value

The width of a pixel. (Akoya pixel is 377nm square)

constraint value
type number
required True

resolution_x_unit

The unit of measurement of width of a pixel.(nm) Leave blank if not applicable.

constraint value
enum mm, um, or nm
required False
required if resolution_x_value present

resolution_y_value

The height of a pixel. (Akoya pixel is 377nm square)

constraint value
type number
required True

resolution_y_unit

The unit of measurement of height of a pixel. (nm) Leave blank if not applicable.

constraint value
enum mm, um, or nm
required False
required if resolution_y_value present

resolution_z_value

Optional if assay does not have multiple z-levels. Note that this is resolution within a given sample: z-pitch (resolution_z_value) is the increment distance between image slices (for Akoya, z-pitch=1.5um) ie. the microscope stage is moved up or down in increments of 1.5um to capture images of several focal planes. The best one will be used & the rest discarded. The thickness of the sample itself is sample metadata. Leave blank if not applicable.

constraint value
type number
required False

resolution_z_unit

The unit of incremental distance between image slices. Leave blank if not applicable.

constraint value
enum mm, um, or nm
required False
required if resolution_z_value present

Level 3

preparation_instrument_vendor

The manufacturer of the instrument used to prepare the sample for the assay.

constraint value
enum CODEX
required True

preparation_instrument_model

The model number/name of the instrument used to prepare the sample for the assay.

constraint value
enum version 1 robot or prototype robot - Stanford/Nolan Lab
required True

number_of_antibodies

Number of antibodies.

constraint value
type integer
required True

number_of_channels

Number of fluorescent channels imaged during each cycle.

constraint value
type integer
required True

number_of_cycles

Number of cycles of 1. oligo application, 2. fluor application, 3. washes.

constraint value
type integer
required True

section_prep_protocols_io_doi

DOI for protocols.io referring to the protocol for preparing tissue sections for the assay.

constraint value
required True
pattern (regular expression) 10\.17504/.*
url prefix: https://dx.doi.org/

reagent_prep_protocols_io_doi

DOI for protocols.io referring to the protocol for preparing reagents for the assay.

constraint value
required True
pattern (regular expression) 10\.17504/.*
url prefix: https://dx.doi.org/

antibodies_path

Relative path to file with antibody information for this dataset.

constraint value
required True

contributors_path

Relative path to file with ORCID IDs for contributors for this dataset.

constraint value
required True

data_path

Relative path to file or directory with instrument data. Downstream processing will depend on filename extension conventions.

constraint value
required True


Directory schemas

Version 1-with-dataset-json (use this one)
pattern required? description
[^/]*NAV[^/]*\.tif (example: NAV.tif)   Navigational Image showing Region of Interest (Keyance Microscope only)
[^/]*\.pdf (example: summary.pdf)   [QA/QC] PDF export of Powerpoint slide deck containing the Image Analysis Report
(raw|processed)/config\.txt|(src_[^/]*|drv_[^/]*|extras)/[sS]egmentation\.json   Sanity check that verifies the existence of at least one of these files. This is required for the HuBMAP processing pipeline
raw/reg_[^/]*\.png (example: raw/reg_00.png)   Region overviews
(raw|src_[^/]*)/[Ee]xperiment\.json   JSON file produced by the Akoya software which contains the metadata for the experiment, including the software version used, microscope parameters, channel names, pixel dimensions, etc. (required for HuBMAP pipeline)
(raw|src_[^/]*)/dataset\.json (example: raw/dataset.json) Additional CODEX specific metadata file
processed/HandE\.tif   HandE image
processed/HandE_RGB\.tif   HandE RGB image
processed/HandE_RGB_thumbnail.jpg   HandE RGB thumbnail
(raw|processed)/config\.txt   Configuration file with information needed for the HuBMAP processing pipeline
(raw|src_.*)/[cC]yc.*_reg.*/.*_Z.*_CH.*\.tif TIFF files produced by the experiment. General folder format: Cycle(n)_Region(n)_date; General file format: name_tileNumber(n)_zplaneNumber(n)_channelNumber(n)
src_.*/cyc.*_reg.*_.*/.*\.gci   Group Capture Information File (Keyance Microscope only)
(raw|src_.*)/.* Raw data directory.
(processed|drv_[^/]*)/.* Processed files produced by the Akoya software or alternative software.
extras/dir-schema-v1-with-dataset-json Empty file whose presence indicates the version of the directory schema in use
extras\/.*   Folder for general lab-specific files related to the dataset. [Exists in all assays]
Version 0
pattern required? description
[^/]*NAV[^/]*\.tif (example: NAV.tif)   Navigational Image showing Region of Interest (Keyance Microscope only)
[^/]*\.pdf (example: summary.pdf)   [QA/QC] PDF export of Powerpoint slide deck containing the Image Analysis Report
(raw|processed)/config\.txt|(raw|src_[^/]*|drv_[^/]*)/[sS]egmentation\.json Sanity check that verifies the existence of at least one of these files. This is required for the HuBMAP processing pipeline
raw/reg_[^/]*\.png (example: raw/reg_00.png)   Region overviews
(raw|src_[^/]*)/[Ee]xperiment\.json JSON file produced by the Akoya software which contains the metadata for the experiment, including the software version used, microscope parameters, channel names, pixel dimensions, etc. (required for HuBMAP pipeline)
processed/HandE\.tif   HandE image
processed/HandE_RGB\.tif   HandE RGB image
processed/HandE_RGB_thumbnail.jpg   HandE RGB thumbnail
(raw|processed)/config\.txt   Configuration file with information needed for the HuBMAP processing pipeline
(raw|src_.*)/[cC]yc.*_reg.*/.*_Z.*_CH.*\.tif TIFF files produced by the experiment. General folder format: Cycle(n)_Region(n)_date; General file format: name_tileNumber(n)_zplaneNumber(n)_channelNumber(n)
src_.*/cyc.*_reg.*_.*/.*\.gci   Group Capture Information File (Keyance Microscope only)
(raw|src_.*)/.* Raw data directory.
(processed|drv_[^/]*)/.* Processed files produced by the Akoya software or alternative software.
extras\/.*   Folder for general lab-specific files related to the dataset. [Exists in all assays]