trace_3way_coloc

Reliability status: stable

Compute three-way co-localization frequencies with bootstrapping.

A script for performing three-way co-localization analysis in 4M (Multi-way Measurement of Molecular interactions in space) data. This tool analyzes spatial co-localization between a specified anchor barcode and all possible pairs of other barcodes in 3D chromatin trace data.

The script calculates three-way co-localization frequencies based on a distance cutoff and performs bootstrapping to estimate statistical confidence (mean and standard error). It generates a heatmap showing the frequency of interaction between the anchor and all possible pairs of other barcodes.

This is particularly useful for analyzing higher-order chromatin organization and complex spatial relationships in microscopy data.

usage: trace_3way_coloc [-h] --input INPUT --anchors ANCHORS [ANCHORS ...]
                        [--cutoff CUTOFF] [--vmin VMIN] [--vmax VMAX]
                        [--bootstrapping_cycles BOOTSTRAPPING_CYCLES]
                        [--output OUTPUT] [--output_format {png,svg,pdf}]
                        [--pipe]

Named Arguments

--input

Path to input trace table (ECSV format).

--anchors

List of anchor barcode numbers.

--cutoff

Distance cutoff for co-localization. Default = 0.2 um

Default: 0.2

--vmin

Minimum value for colormap scale.

--vmax

Maximum value for colormap scale.

--bootstrapping_cycles

Number of bootstrap iterations.

Default: 10

--output

Output file for the plot.

Default: 'threeway_coloc_plot.png'

--output_format

Possible choices: png, svg, pdf

Output image format. Default = png.

Default: 'png'

--pipe

inputs Trace file list from stdin (pipe)

Default: False

Output Files

For each trace file analyzed, the script generates:

  1. [output]_anchor_[anchor].npy: Mean three-way co-localization matrix for the selected anchor barcode.

  2. [output]_anchor_[anchor].[format]: Heatmap of three-way co-localization frequencies between the anchor barcode and all possible pairs of other barcodes.

  3. [output]_anchor_[anchor]_sem.[format]: Heatmap of the standard error of the mean (SEM) for the bootstrapped three-way co-localization frequencies.

Examples

  1. Analyze a single trace file with default parameters:

    trace_3way_coloc --input traces.ecsv --anchor 42

  2. Analyze with custom distance cutoff and more bootstrap cycles:

    trace_3way_coloc --input traces.ecsv --anchor 42 --cutoff 0.25 --bootstrapping_cycles 100

Notes

  • The script requires the ChromatinTraceTable class from the matrixOperations module

  • Input files must be in ECSV format compatible with ChromatinTraceTable.load()

  • Bootstrapping is used to estimate mean and standard error of co-localization frequencies

  • The distance cutoff is in micrometers (µm)