trace_filter

Reliability status: stable

Localization quality filtering

trace_filter can remove spots by comparing values in a localization table against user-provided minimum thresholds. Pass the localization table with --localization_file, then add any combination of quality filters:

  • --intensity_min: minimum spot intensity. This single argument supports both localization-table formats: it filters on mean_intensity when that column is present in newer tables, or on peak for legacy tables.

  • --snr_min: minimum snr.

  • --spot_pixel_percentage_min: minimum spot_pixel_percentage.

  • --skew_min: minimum skew.

  • --patch_size_min: minimum patch_size.

  • --roundness_min: minimum roundness.

  • --object_class_min: minimum object_class; use --object_class_min 1 to keep spots classified as spots (object_class >= 1) and remove background localizations (object_class == 0).

When multiple quality filters are provided, a spot is kept only if it satisfies all requested minimum thresholds.

Example:

trace_filter \
  --input Trace.ecsv \
  --localization_file Localizations.ecsv \
  --intensity_min 1000 \
  --snr_min 5 \
  --object_class_min 1

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 quality metrics
$ trace_filter --input Trace.ecsv --localization_file Localizations.ecsv --intensity_min 1000 --snr_min 5 --object_class_min 1

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

Usage

usage: trace_filter [-h] [--input INPUT] [-O OUTPUT] [--pipe]
                    [--output_format {png,svg,pdf}] [--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] [--snr_min SNR_MIN]
                    [--spot_pixel_percentage_min SPOT_PIXEL_PERCENTAGE_MIN]
                    [--skew_min SKEW_MIN] [--patch_size_min PATCH_SIZE_MIN]
                    [--object_class_min OBJECT_CLASS_MIN]
                    [--roundness_min ROUNDNESS_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

--output_format

Possible choices: png, svg, pdf

Output image format. Default = png.

Default: 'png'

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.

Localization quality filtering

--localization_file

Name of input localizations file.

--intensity_min

Minimum intensity threshold for localizations. Uses mean_intensity for new localization tables and peak for legacy tables.

Default: 0.0

--snr_min

Minimum snr threshold for localizations.

Default: 0.0

--spot_pixel_percentage_min

Minimum spot_pixel_percentage threshold for localizations.

Default: 0.0

--skew_min

Minimum skew threshold for localizations.

Default: 0.0

--patch_size_min

Minimum patch_size threshold for localizations.

Default: 0.0

--object_class_min

Minimum object_class threshold for localizations.

Default: 0.0

--roundness_min

Minimum roundness 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