trace_physical_vs_genomic_distance

Reliability status: development

trace_physical_vs_genomic_distance.py summarizes how physical chromatin-trace distances change with genomic separation. It reads a chromatin trace table, computes pairwise distances between all barcode loci in each trace, bins those distances by genomic distance, and writes a CSV table that can also be plotted as a log-log physical-vs-genomic-distance curve.

Calculate physical distances as a function of genomic distances from a chromatin trace table.

usage: trace_physical_vs_genomic_distance [-h] --input INPUT [--output OUTPUT]
                                          [--interloci_output INTERLOCI_OUTPUT]
                                          [--plot PLOT]
                                          [--gen_dist_bins GEN_DIST_BINS]
                                          [--dist_threshold DIST_THRESHOLD]
                                          [--experiment EXPERIMENT] [--no_3d]
                                          [--quiet]

Named Arguments

--input

Input chromatin trace table (.ecsv, .dat, .4dn, or .csv).

--output

Output CSV for binned physical-vs-genomic distances.

Default: 'binned_physical_vs_genomic_distances.csv'

--interloci_output

Optional CSV for consecutive-locus genomic distances.

--plot

Optional output filename for a log-log distance plot.

Default: '_physical_vs_genomic_plot.png'

--gen_dist_bins

Number of genomic-distance bins. Default: 50

Default: 50

--dist_threshold

Maximum physical distance retained before replacing with NaN. Default: infinity

Default: numpy.inf

--experiment

Experiment or replicate label to include in the output CSV.

--no_3d

Only calculate X, Y, and Z axis distances.

Default: False

--quiet

Disable progress bars.

Default: False

What the script computes

  1. The script loads an input trace table supported by ChromatinTraceTable (.ecsv, .dat, .4dn, or .csv).

  2. Each trace is converted into a NumPy array with one row per trace, one column per barcode, and X/Y/Z coordinates in the final dimension.

  3. Genomic separation is computed from barcode midpoint positions, using (Chrom_Start + Chrom_End) / 2, and is reported in kilobase pairs (kbp).

  4. Physical pairwise distances are computed for:

    • full 3D Euclidean distance, unless --no_3d is used;

    • projected X-axis distance;

    • projected Y-axis distance;

    • projected Z-axis distance.

  5. Physical distances above --dist_threshold are replaced by NaN before summarization.

  6. Genomic distances are split into --gen_dist_bins equally spaced bins, and the median physical distance is reported for each bin and axis.

Output CSV columns

The main output CSV contains one row per genomic-distance bin and axis:

  • genomic distance (kbp): midpoint of the genomic-distance bin.

  • log10 genomic dist (kbp): log10-transformed bin midpoint.

  • median euclidean distance (nm): median physical distance for barcode pairs in the bin.

  • log10 median dist (nm): log10-transformed median physical distance.

  • n_data: number of non-NaN physical distances used in the bin.

  • experiment: experiment label from --experiment, or exp_None when no label is supplied.

  • axis: one of 3D, X, Y, or Z.

If --interloci_output is supplied, the script also writes a CSV containing genomic distances between consecutive barcode loci.

Plot and power-law fit

When --plot is provided, the script saves a stacked log-log plot with one panel per calculated axis. The x-axis is shared and shown only on the bottom panel, while a single shared y-axis label spans the panels to avoid label overlap.

For every axis panel and experiment, the script fits the binned median distances to a power-law model:

physical_distance = a * genomic_distance^b

The fit is performed by linear regression in log10 space. The plotted fit line is shown together with a 95% confidence interval for the fitted mean response. Each panel legend reports both fitted coefficients:

  • a: the scale coefficient.

  • b: the power-law exponent.

Example

trace_physical_vs_genomic_distance.py \
  --input traces_KC_AB_merged.ecsv \
  --output binned_physical_vs_genomic_distances.csv \
  --interloci_output interloci_genomic_distances.csv \
  --plot _physical_vs_genomic_plot.png \
  --gen_dist_bins 50 \
  --dist_threshold 1000 \
  --experiment KC_AB

The plot filename is appended to the input stem by default. For the example above, the figure is saved as traces_KC_AB_merged_physical_vs_genomic_plot.png.