PeacoQC-CLI

Command-line tool for PeacoQC (Peak-based Quality Control) for flow cytometry FCS files. This CLI provides a simple interface to run quality control on one or more FCS files with parallel processing support.

Installation

From Source

git clone <repository-url>
cd peacoqc-cli
cargo build --release

The binary will be at target/release/peacoqc.

Using Cargo

Install the binary as a cargo tool by pointing to its location (e.g. using the path of the repo cloned above):

cargo install --path peacoqc-cli

Usage

Basic Usage (Single File)

Process a single FCS file:

peacoqc input.fcs

With output file:

peacoqc input.fcs -o output.fcs

Multiple Files

Process multiple files in parallel:

peacoqc file1.fcs file2.fcs file3.fcs

With output directory:

peacoqc file1.fcs file2.fcs file3.fcs -o /path/to/output/

Directory Processing

Process all FCS files in a directory (recursively):

peacoqc /path/to/data/

The tool will:

• Recursively find all .fcs files in the directory
• Process them in parallel
• Save outputs to the specified output directory (or alongside input files with _cleaned suffix)

Options

peacoqc [OPTIONS] <INPUT_FILES>...

Arguments:
  <INPUT_FILES>...  Path(s) to input FCS file(s) or directory containing FCS files

Options:
  -o, --output <OUTPUT_DIR>      Output directory for cleaned FCS files
  -c, --channels <CHANNELS>      Channels to analyze (comma-separated, e.g., "FSC-A,SSC-A,FL1-A")
  -m, --qc-mode <QC_MODE>        Quality control mode [default: all] [possible values: all, it, mad, none]
  --mad <MAD>                    MAD threshold (default: 6.0) - Higher = less strict
  --it-limit <IT_LIMIT>          Isolation Tree limit (default: 0.6) - Higher = less strict
  --consecutive-bins <BINS>      Consecutive bins threshold (default: 5)
  --remove-zeros                 Remove zeros before peak detection
  --remove-margins               Remove margin events before QC (default: true)
  --remove-doublets              Remove doublets before QC (default: true)
  --doublet-nmad <NMAD>          Doublet nmad threshold (default: 4.0)
  --report <REPORT_PATH>         Save QC report as JSON (file for single input, directory for multiple)
  -v, --verbose                  Verbose output
  -h, --help                     Print help
  -V, --version                  Print version

Examples

Process Single File

# Basic processing
peacoqc sample.fcs

# With custom channels
peacoqc sample.fcs -c FL1-A,FL2-A,FL3-A

# Save report
peacoqc sample.fcs --report report.json

# Verbose output
peacoqc sample.fcs -v

Process Multiple Files

# Process all files in directory
peacoqc /path/to/data/ -o /path/to/output/

# Process specific files
peacoqc file1.fcs file2.fcs file3.fcs -o ./cleaned/

# Save individual reports
peacoqc /path/to/data/ --report /path/to/reports/

Custom QC Settings

# Use only Isolation Tree method
peacoqc sample.fcs -m it

# Adjust MAD threshold (higher = less strict)
peacoqc sample.fcs --mad 8.0

# Adjust Isolation Tree limit
peacoqc sample.fcs --it-limit 0.7

# Disable margin/doublet removal
peacoqc sample.fcs --no-remove-margins --no-remove-doublets

Performance

The CLI automatically processes files in parallel:

• Multiple files: Processed simultaneously using all available CPU cores
• Multiple channels: Processed in parallel within each file
• Multiple bins: Processed in parallel within each channel

Expected speedup:

• Single file with many channels: 2-4x speedup on typical multi-core systems
• Multiple files: ~N cores speedup (e.g., 8 files on 8 cores → ~8x speedup)

Output

Console Output

The tool prints progress and summary information:

🧬 PeacoQC - Flow Cytometry Quality Control
============================================

📂 Found 5 file(s) to process

✅ Processing Complete!
   Processed: 5 file(s)
   Successful: 5
   ⏱️  Total time: 12.34s

With --verbose flag, additional details are shown for each file.

Reports

Reports are saved as JSON files with the following structure:

{
  "filename": "sample.fcs",
  "n_events_before": 50000,
  "n_events_after": 47500,
  "percentage_removed": 5.0,
  "it_percentage": 3.2,
  "mad_percentage": 1.8,
  "consecutive_percentage": 0.5,
  "processing_time_ms": 1234
}

For multiple files:

• If --report points to a directory: Individual JSON files are created for each input file
• If --report points to a file: A combined report with all results is created

Output Files (FCS)

⚠️ Note: FCS file writing is currently not implemented. The flow-fcs crate (which peacoqc-cli uses for FCS file support) is currently read-only.

To achieve feature parity with the R PeacoQC package (which saves filtered FCS files with save_fcs=TRUE), FCS file writing needs to be implemented in the flow-fcs crate first. Once implemented:

• Output files will be saved with _cleaned suffix (e.g., sample.fcs → sample_cleaned.fcs)
• If output directory is specified, files will maintain their original names with _cleaned suffix
• Filtered FCS files will contain only the events that passed quality control

This feature is planned and will be added when flow-fcs supports writing FCS files.

Error Handling

The CLI continues processing even if individual files fail:

• Successful files: Processed and included in results
• Failed files: Error messages are printed, processing continues
• Exit code: Returns non-zero exit code if any files failed

Integration with peacoqc-rs

This CLI is built on top of the peacoqc-rs library, which provides:

• Trait-based design for maximum flexibility
• Efficient parallel processing
• Comprehensive quality control algorithms
• Integration with flow-fcs for FCS file support

See the peacoqc-rs documentation for library usage.

Attribution

This CLI tool is built on top of peacoqc-rs, which implements the PeacoQC algorithm. We gratefully acknowledge the original authors:

Original Paper:

• Emmaneel, A., Quintelier, K., Sichien, D., Rybakowska, P., Marañón, C., Alarcón-Riquelme, M. E., Van Isterdael, G., Van Gassen, S., & Saeys, Y. (2022). PeacoQC: Peak-based selection of high quality cytometry data. Cytometry A, 101(4), 325-338. https://doi.org/10.1002/cyto.a.24501

Original R Implementation:

• GitHub: https://github.com/saeyslab/PeacoQC
• Authors: Annelies Emmaneel, Katrien Quintelier, and the Saeys Lab

License

MIT License - see LICENSE file for details