trace_filter

Reliability status: stable

Chromatin Trace Filtering Utility

This script processes and filters chromatin trace files based on various criteria:

  • Spatial coordinates (x, y, z)

  • Minimum number of barcodes per trace

  • Duplicate spot removal

  • Barcode-specific filtering

  • Label-based filtering

  • Localization intensity thresholding

The script can process single files or multiple files via pipe input.

Outputs

  1. Filtered trace file (.ecsv) with naming convention:

    • [original_filename]_[output_tag]_[label_tag].ecsv

  2. For intensity filtering:

    • Histogram plots of localization intensities (before and after filtering)

  3. For duplicate barcode cleaning:

    • Statistics plots (.png) showing number of spots with same barcode per trace

Examples

# Basic filtering with spatial constraints and minimum barcode requirement
$ trace_filter --input Trace.ecsv --z_min 4 --z_max 5 --y_max 175 --output zy_filtered --n_barcodes 3

# Remove duplicate spots and specific barcodes
$ trace_filter --input Trace.ecsv --clean_spots --remove_barcode 1,3,5

# Keep only traces with a specific label
$ trace_filter --input Trace.ecsv --keep_label region1

# Remove traces with a specific label
$ trace_filter --input Trace.ecsv --remove_label region1

# Filter by localization intensity
$ trace_filter --input Trace.ecsv --localization_file Localizations.ecsv --intensity_min 1000

# Process multiple files via pipe
$ ls *Trace.ecsv | trace_filter --pipe --n_barcodes 3

Usage

usage: trace_filter [-h] [--input INPUT] [-O OUTPUT] [--pipe]
                    [--n_barcodes N_BARCODES] [--clean_spots]
                    [--remove_barcode REMOVE_BARCODE]
                    [--remove_label REMOVE_LABEL] [--keep_label KEEP_LABEL]
                    [--localization_file LOCALIZATION_FILE]
                    [--intensity_min INTENSITY_MIN] [--z_min Z_MIN]
                    [--z_max Z_MAX] [--y_min Y_MIN] [--y_max Y_MAX]
                    [--x_min X_MIN] [--x_max X_MAX]

Basic arguments

One of –input or –pipe is required.

--input

Name of input trace file (ECSV format).

-O, --output

Tag to add to the output file.

Default: 'filtered'

--pipe

inputs Trace file list from stdin (for batch processing)

Default: False

Filtering options

--n_barcodes

Minimum number of barcodes by trace to keep. Filtering performed last because the previous filters generate traces with fewer spots.

Default: 2

--clean_spots

Removes both spots with same UID and barcodes repeated in a single trace.

Default: False

--remove_barcode

Comma-separated list of barcode IDs to remove (e.g., 1,2,3)

--remove_label

Provide a label name to remove traces with this label.

--keep_label

Select traces containing this label, removes all other traces.

Intensity filtering

--localization_file

Name of input localizations file.

--intensity_min

Minimum intensity threshold for localizations.

Default: 0.0

Coordinate filtering

Coordinate limits (default: 0 to infinity)

--z_min

Z minimum for a localization.

Default: 0

--z_max

Z maximum for a localization.

Default: numpy.inf

--y_min

Y minimum for a localization.

Default: 0

--y_max

Y maximum for a localization.

Default: numpy.inf

--x_min

X minimum for a localization.

Default: 0

--x_max

X maximum for a localization.

Default: numpy.inf