Spot Quality table

Requirement level: recommended

Summary

This table is highly recommended and it is designed to provide quality metrics for the Spot localization, information about the optical Channel that was used to image the Spot, and various aberration corrections that have been applied prior to localization (e.g., drift correction, chromatic correction, etc.).

Because the metrics used to quantify Spot detection accuracy and precision are not trivial and lacking a widely shared consensus, the specific columns in this table remain largely at the user’s discretion and should be described with sufficient details to ensure interpretation and reproducibility.

However, in order to align with existing 4DN-BINA-OME Microscopy Metadata specifications, the use of specific column names and descriptions is conditionally required in case the described metric is reported. As an example, the column name X_Drift is conditionally required in case the user intends to report a comparison between the Observed vs. Expected (i.e., based on a fiducial reference) positions of a detected Spot.

The table is indexed by Spot_ID and each row corresponds to a DNA or RNA bright Spot. The order of all other columns (including those conditionally required) and of the rows are at the user’s discretion.

Example

Spot fit quality

##FOF-CT_version=v0.1
##Table_namespace=4dn_FOF-CT_quality
##XYZ_unit=micron
##intensity_unit=photonCount
#Software_Title: SpotQualityCheck
#Software_Type: QualityControl
#Software_Authors: John Doe et al.
#Software_Description: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
#Software_Repository: https://eample.com
#Software_PreferredCitationID: https://doi.org/00000
#lab_name: Nobel
#experimenter_name: John Doe
#experimenter_contact: john.doe@email.com
#^Channel_ID: A unique identifier that refers to the Channel that was used to image this Spot.
#^Peak_Intensity: The signal intensity of the brightest pixel within a bright Spot (i.e. local maximum).
#^Raw_X: the original fit x-position relative to the camera and objective, (prior to drift correction, chromatic correction, or conversion to stage coordinates). This is the appropriate coordinate system for correcting optical aberrations.
#^Raw_Y: the original fit y-position relative to the camera and objective, (prior to drift correction, chromatic correction, or conversion to stage coordinates). This is the appropriate coordinate system for correcting optical aberrations.
#^Raw_Z: the original fit z-position relative to the camera and objective, (prior to drift correction, chromatic correction, or conversion to stage coordinates). This is the appropriate coordinate system for correcting optical aberrations.
#^X_Drift: the distance in nm the spot was moved in x based on fiducial tracking
#^Y_Drift: the distance in nm the spot was moved in y based on fiducial tracking
#^Z_Drift: the distance in nm the spot was moved in z based on fiducial tracking
#^X_Chromatic_Shift: the distance in nm the spot was moved in x based on chromatic correction map
#^Y_Chromatic_Shift: the distance in nm the spot was moved in y based on chromatic correction map
#^Z_Chromatic_Shift: the distance in nm the spot was moved in z based on chromatic correction map
#^X_Loc_Precision: lower and upper bound of 95% confidence interval on X-position after fit
#^Y_Loc_Precision: lower and upper bound of 95% confidence interval on Y-position after fit
#^Z_Loc_Precision: lower and upper bound of 95% confidence interval on Z-position after fit
#additional_tables: 4dn_FOF-CT_core, 4dn_FOF-CT_rna, 4dn_FOF-CT_trace, 4dn_FOF-CT_cell
##columns=(Spot_ID, Channel_ID, Peak_Intensity, Raw_X, Raw_Y, Raw_Z, X_Drift, Y_Drift, Z_Drift, X_Chromatic_Shift, Y_Chromatic_Shift, Z_Chromatic_Shift, X_Loc_Precision, Y_Loc_Precision, Z_Loc_Precision)
1, 1, 100, 1.1, 1.05, 1.2, 0.1, 0.05, 0.2, 0.2, 0.2, 0.2, 0.01, 0.01, 0.01
2, 1, 200, 1.11, 1.055, 1.22, 0.11, 0.055, 0.22, 0.22, 0.22, 0.22, 0.012, 0.012, 0.012
3, 2, 500, 1.12, 1.054, 1.21, 0.12, 0.054, 0.21, 0.22, 0.22, 0.22, 0.012, 0.012, 0.012
4, 3, 333, 1.13, 1.15, 1.202, 0.13, 0.15, 0.202, 0.23, 0.23, 0.23, 0.013, 0.013, 0.013

File Header

  • The first line in the header is always “##FOF-CT_version=vX.X”

  • The second line in the header is always “##Table_namespace=4dn_FOF-CT_quality”

The header MUST contain a mandatory set of fields that describe any algorithm that was used to produce/process data in this table. In case more than one algorithm were used, please use the same set of fields for each of them.

The header MUST include a detailed description of each optional columns used.

Name

Description

Example

Conditional requirement conditions

##FOF-CT_version=

Version of the FOF format used in this case.

v0.1

##Table_namespace=

Identifier for this type of table. Value must be as in the example.

4dn_FOF-CT_quality

#lab_name:

name of the lab where the experiment was performed.

Nobel

#experimenter_name:

name of the person performing the experiment.

John Doe

#experimenter_contact:

email address of the person performing the experiment.

john.doe@email.com

#description:

A free-text, description of the experiment and of the data recorded in this table. This description should provide a clear understanding of the process utilized to produce the data and contain sufficient details to ensure interpretation and reproducibility.

#Software_Title:

The name of the Software(s) that were used in this case for localizing individual FISH-omics bright Spots and/or to produce three-dimensional (3D) polymeric chromatin Traces.

ChrTracer3

#Software_Type:

The type of this Software. Allowed values: SpotLoc, Tracing, SpotLoc+Tracing, Segmentation, QC, Other

SpotLoc+Tracing

#Software_Authors:

The Name(s) of the individual Author(s) of this Software. In case there are more than one Authors, individual names should be listed as follows, Doe, John; Smith, Jane; etc,.

Mateo, LJ; Sinnott-Armstrong, N; Boettiger, AN

#Software_Description:

A free-text, description of this Software. This description should provide a detailed understanding of the algortithm and of the analysis parameters that were used, in order to guarantee interpretation and reproducibility.

ChrTracer3 software was developed for analysis of raw DNA labeled images. As an input, it takes an.xlsx table containing information and folder names of the DNA experiment. As an output, it returns tab delimited.txt files with drift-corrected x, y, z positions for all labeled barcodes. These can be used directly to calculate the nm scale distances between all pairs of labeled loci. The current version of the software as of this writing is ChrTracer3.

#Software_Repository:

The URL of any repository or archive where the Software executable release can be obtained.

https://github.com/BoettigerLab/ORCA-public

#Software_PreferredCitationID:

The Unique Identifier for the preferred/primary publication describing this Software. Examples include, Digital Object Identifier (DOI), PubMed Central Identifier (PMCID), ArXiv.org ID etc,.

https://doi.org/10.1038/s41596-020-00478-x

#additional_tables:

list of the additional tables being submitted. Note: use a comma to separate each table name from the next.

4dn_FOF-CT_core, 4dn_FOF-CT_rna, 4dn_FOF-CT_bio, 4dn_FOF-CT_trace, 4dn_FOF-CT_cell

#Intensity_Measurement_Method:

If relevant, the method that was used to performed intensity measurements. In particular, sufficient information should be provided to document how digital intensity signals were converted in Photon conunts.

Spot centroid intensity.

Conditional requirement: this MUST be reported if any intensity metrics are reported.

#^Channel_ID:

A unique identifier that refers to the Channel that was used to image this Spot.

#^Fluorophore_ID:

A unique identifier that refers to the Fluorophore whose Emission is utilized to detect this Spot.

#^Centroid_Intensity:

The signal intensity of the pixel occupying the center-of-mass within a bright Spot (i.e. centroid).

Conditional requirement: this column name should be used if this metric is reported.

#^Peak_Intensity:

The signal intensity of the brightest pixel within a bright Spot (i.e. local maximum).

Conditional requirement: this column name should be used if this metric is reported.

#^Raw_X:

The Raw sub-pixel X coordinate of this bright Spot relative to the optical system (i.e., Objective and Detector), as determined before any performed post-processing correction procedures (i.e. drift correction, chromatic correction etc). This is the appropriate coordinate system for correcting optical aberrations.

Conditional requirement: this column name should be used if this metric is reported.

#^Raw_Y:

The Raw sub-pixel Y coordinate of this bright Spot relative to the optical system (i.e., Objective and Detector), as determined before any performed post-processing correction procedures (i.e. drift correction, chromatic correction etc). This is the appropriate coordinate system for correcting optical aberrations.

Conditional requirement: this column name should be used if this metric is reported.

#^Raw_Z:

The Raw sub-pixel Z coordinate of this bright Spot relative to the optical system (i.e., Objective and Detector), as determined before any performed post-processing correction procedures (i.e. drift correction, chromatic correction etc). This is the appropriate coordinate system for correcting optical aberrations.

Conditional requirement: this column name should be used if this metric is reported.

#^X_Drift:

This field captures the offset in the observed X-coordinate of the Intensity maxima or the Intensity centre of gravity of the bright Spot when comparing the Observed vs. Expected (i.e., based on a fiducial reference) positions. This shall be calculates as: √(Xe - Xo)^2, and reported in physical distance using the unit indicated in the header.

Conditional requirement: this column name should be used if this metric is reported.

#^Y_Drift:

This field captures the offset in the observed Y-coordinate of the Intensity maxima or the Intensity centre of gravity of the bright Spot when comparing the Observed vs. Expected (i.e., based on a fiducial reference) positions. This shall be calculates as: √(Ye - Yo)^2, and reported in physical distance using the unit indicated in the header.

Conditional requirement: this column name should be used if this metric is reported.

#^Z_Drift:

This field captures the offset in the observed Z-coordinate of the Intensity maxima or the Intensity centre of gravity of the bright Spot when comparing the Observed vs. Expected (i.e., based on a fiducial reference) positions. This shall be calculates as: √(Ze - Zo)^2, and reported in physical distance using the unit indicated in the header.

Conditional requirement: this column name should be used if this metric is reported.

#^X_Chromatic_Shift:

This field captures the offset in the observed X-coordinate of the Intensity maxima or the Intensity centre of gravity of the bright Spot when comparing the Reference (λR) vs. the Test (λT) wavelengths. This shall be calculated as: √(XλT - XλR)^2. This offset could be reported either in number of Pixels or in physical Distance, when a sub-Pixel offset needs to be calculated.

Conditional requirement: this column name should be used if this metric is reported.

#^Y_Chromatic_Shift:

This field captures the offset in the observed Y-coordinate of the Intensity maxima or the Intensity centre of gravity of the bright Spot when comparing the Reference (λR) vs. the Test (λT) wavelengths. This shall be calculated as: √(YλT - YλR)^2. This offset could be reported either in number of Pixels or in physical Distance, when a sub-Pixel offset needs to be calculated.

Conditional requirement: this column name should be used if this metric is reported.

#^Z_Chromatic_Shift:

This field captures the offset in the observed Z-coordinate of the Intensity maxima or the Intensity centre of gravity of the bright Spot when comparing the Reference (λR) vs. the Test (λT) wavelengths. This shall be calculated as: √(ZλT - ZλR)^2. This offset could be reported either in number of Pixels or in physical Distance, when a sub-Pixel offset needs to be calculated.

Conditional requirement: this column name should be used if this metric is reported.

#^X_Loc_Error:

Metric used to quantify the Error associated with the estimation of the X-axis localization of this bright Spot. Whatever method is used, a description of how this metric was computed and of the Software that was employed must be provided in the header of the table. Such description must contain enough details to allow interpretation and reproducibility.

Conditional requirement: this column name should be used if this metric is reported.

#^Y_Loc_Error:

Metric used to quantify the Error associated with the estimation of the Y-axis localization of this bright Spot. Whatever method is used, a description of how this metric was computed and of the Software that was employed must be provided in the header of the table. Such description must contain enough details to allow interpretation and reproducibility.

Conditional requirement: this column name should be used if this metric is reported.

#^Z_Loc_Error:

Metric used to quantify the Error associated with the estimation of the Z-axis localization of this bright Spot. Whatever method is used, a description of how this metric was computed and of the Software that was employed must be provided in the header of the table. Such description must contain enough details to allow interpretation and reproducibility.

Conditional requirement: this column name should be used if this metric is reported.

#^X_Loc_Precision

Metric used to quantify the Precision associated with the estimation of the X-axis localization of this bright Spot. Different methods might be used. The Cramer-Rao Lower and Upper Bounds methods is widely accepted, but it tends to overestimate the Precision value. Alternatively, the Thompson method, by which Precision is estimated to be proportional to Photon Count, can also be used even though this method highly overestimates the Precision. Whatever method is used, description of how this metric was computed and of the Software that was employed must be provided in the header of the table. Such description must contain enough details to allow interpretation and reproducibility.

#^Y_Loc_Precision

Metric used to quantify the Precision associated with the estimation of the Y-axis localization of this bright Spot. Different methods might be used. The Cramer-Rao Lower and Upper Bounds methods is widely accepted, but it tends to overestimate the Precision value. Alternatively, the Thompson method, by which Precision is estimated to be proportional to Photon Count, can also be used even though this method highly overestimates the Precision. Whatever method is used, description of how this metric was computed and of the Software that was employed must be provided in the header of the table. Such description must contain enough details to allow interpretation and reproducibility.

#^Z_Loc_Precision

Metric used to quantify the Precision associated with the estimation of the Z-axis localization of this bright Spot. Different methods might be used. The Cramer-Rao Lower and Upper Bounds methods is widely accepted, but it tends to overestimate the Precision value. Alternatively, the Thompson method, by which Precision is estimated to be proportional to Photon Count, can also be used even though this method highly overestimates the Precision. Whatever method is used, description of how this metric was computed and of the Software that was employed must be provided in the header of the table. Such description must contain enough details to allow interpretation and reproducibility.

#^optional_column_1:

#^optional_column_2:

#^optional_column_3:

##XYZ_unit=

The unit used to represent XYZ locations or distances in this table. Note: use micron (instead of µm) to avoid problem with special, Greek symbols. Other allowed values are: nm, mm etc.

micron

##time_unit=

If relevant, the unit used to represent a time interval. Note: use ‘sec’ for seconds, ‘msec’ for milliseconds, ‘min’ for minutes, and ‘hr’ for hours.

sec

Conditional requirement: this MUST be reported if any time metrics are reported.

##intensity_unit=

If relevant, the unit used to represent intensity measurements.

a.u.

Conditional requirement: this MUST be reported if any intensity metrics are reported.

##columns=

list of the data column headers used in the table. Note: enclose the column headers and use a comma to separate each header name from the next.

(Spot_ID, X, Y, Z)

Data Columns

As with all other Spot Data tables in this format, each row corresponds to data associated with an individual Spot.

The first column of this table is always Spot_ID. The content and order of all other columns is largely at user’s discretion. However, in order to align with existing Microscopy Metadata specifications, the use of specific column names and descriptions is conditionally required as indicated below. The order of all other columns (including those conditionally requried) and of the rows are at the user’s discretion.

Name

Description

Example

Conditional requirement conditions

Spot_ID

A unique identifier for this bright Spot.

1

conditionally_required_column_1:

one of the conditionally required columns desribed in the header

conditionally_required_column_2:

one of the conditionally required columns desribed in the header

conditionally_required_column_3:

one of the conditionally required columns desribed in the header

optional_column_1:

optional_column_2:

optional_column_3: