trace_filter

Reliability status: stable

Localization quality filtering

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

Minimum-threshold filters remove spots whose value is smaller than the provided threshold:

• --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.

• --skew_min: minimum skew.

• --patch_size_min: minimum patch_size.

• --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).

Maximum-threshold filters remove spots whose value is larger than the provided threshold:

• --spot_pixel_percentage_max: maximum spot_pixel_percentage.

• --roundness_max: maximum roundness.

When multiple quality filters are provided, a spot is kept only if it satisfies all requested thresholds. In other words, it must be greater than or equal to each requested minimum and less than or equal to each requested maximum.

When a localization table is provided, trace_filter also writes a filtered localization table next to the filtered trace table. This table contains only the localizations whose Buid values are present as Spot_ID values in the final filtered trace table, after all trace filters have run. The same filtered localization table is used for the *_localization_distribution_fluxes plot, so that the spot statistics describe the spots kept in the trace table.

Example:

trace_filter \
  --input Trace.ecsv \
  --localization_file Localizations.ecsv \
  --intensity_min 1000 \
  --snr_min 5 \
  --object_class_min 1 \
  --spot_pixel_percentage_max 0.7 \
  --roundness_max 0.8

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 --roundness_max 0.8

# 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]
                    [--skew_min SKEW_MIN] [--patch_size_min PATCH_SIZE_MIN]
                    [--object_class_min OBJECT_CLASS_MIN]
                    [--spot_pixel_percentage_max SPOT_PIXEL_PERCENTAGE_MAX]
                    [--roundness_max ROUNDNESS_MAX] [--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

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

--spot_pixel_percentage_max

Maximum spot_pixel_percentage threshold for localizations.

Default: 0.0

--roundness_max

Maximum 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