CLI Reference

The uSort-M command-line interface provides tools for planning experiments, processing sequencing data, and generating outputs.

usortm --help

Commands

Command Description
estimate Quick cost and effort estimation
plan Initialize project from variant list
demux Demultiplex sequencing data (LevSeq barcodes via Dorado, reference alignment, consensus, variant calling)
pick Generate Integra ASSIST hit-picking list (ordered by input library)
report Generate final plate maps, coverage stats, and HTML summary
reorder Generate synthesis ordering files for dropout variants (IDT eBlocks, Twist Gene Fragments, oPools)
platemap Regenerate interactive plate map HTML from existing demux results without re-running demux

usortm estimate

Quick cost and effort estimation without creating a project.

usortm estimate --library-size 500 --seq-length 300

Options

Option Short Description Default
--library-size -n Number of variants required
--seq-length -l Sequence length (bp) 300
--fold-sampling -f Fold oversampling 4.0
--skew -s Library skew (Q90/Q10) 4.0
--sorting-efficiency Fraction of wells with growth 0.67
--machine-rate FACS machine rate ($/hr) 70
--operator-rate FACS operator rate ($/hr) 65
--compare/--no-compare Show traditional comparison True
--json Output as JSON False

Example with custom parameters

usortm estimate \
  --library-size 1500 \
  --seq-length 450 \
  --fold-sampling 10 \
  --skew 6 \
  --machine-rate 50 \
  --operator-rate 40

usortm plan

Initialize a project from a variant list.

usortm plan variants.csv --output my_project/

Arguments

Argument Description
variants_file CSV file with variant definitions

Options

Option Short Description Default
--output -o Output directory usortm_project
--seq-length -l Sequence length (bp) auto-detected from sequences
--fold-sampling -f Fold oversampling 8.0
--skew -s Expected library skew interactive prompt (None)
--target-coverage Target recovery fraction 0.90
--barcodes -b Barcode kit or CSV path levseq
--round -r Sequencing round number (1 for initial sort, 2+ for re-order rounds) 1

Barcode Options

  • levseq - Arnold lab LevSeq barcodes (recommended for ONT)
  • evseq - evSeq dual-indexing system
  • path/to/barcodes.csv - Custom barcode mapping

usortm demux

Demultiplex sequencing data using the LevSeq barcode pipeline. Runs Dorado for barcode demux, minimap2 for reference alignment, and samtools for per-well consensus generation.

usortm demux my_project/ --fastq data.fastq --library-csv variants.csv

Options

Option Short Description Default
--fastq -f Input FASTQ file required
--library-csv -l Library CSV (Name,Sequence columns) — auto-converted to reference FASTA None
--reference -r Reference FASTA for alignment (alternative to --library-csv) None
--barcodes -b Override barcode mapping CSV project default
--mask-config TOML file with custom barcode flanking sequences project mask_config.toml or cutinase defaults
--min-reads Minimum reads per well to call a variant 100
--min-fraction Minimum fraction of reads supporting consensus 0.8
--threads -t Threads for alignment 4
--workers -w Parallel workers for per-well consensus alignment 4
--subsample -n Subsample to this many reads before running the pipeline None
--orient-ref Single reference FASTA for read orientation only (useful for near-identical variant libraries) None
--vector-fasta Vector FASTA with X's marking the variable region; enables flanking region mismatch detection None

usortm pick

Generate hit-picking list from demultiplexing results. Output is formatted for Integra ASSIST PLUS liquid handling robots. The pick list is ordered to match the input library CSV, so variants appear in the same order they were defined.

usortm pick my_project/

Options

Option Short Description Default
--targets -t CSV of specific variants to pick all
--output -o Output file path project/hitlist.csv
--volume -v Transfer volume (µL) 5.0
--target-format Target plate format 384
--fill-order Fill order (row/column) row
--unique-only/--all-hits Pick one well per variant True
--tier Quality tier filter: A (≥100 reads), B (≥50 reads), C (≥20 reads); all require >90% consensus. Use --tier '' to disable. A
--compact/--no-compact Pack recovered hits into adjacent wells; omit empty placeholders for unrecovered variants False
--pileups/--no-pileups Generate per-well pileup HTML visualizations True
--workers -w Parallel workers for pileup generation 4
--include-flank-errors Include wells with flanking region mismatches in the pick list False

Output Format

Semicolon-delimited CSV compatible with Integra ASSIST PLUS:

SampleID;SourcePlateID;SourceWell;TargetPlateID;TargetWell;TransferVolume
K44A;1;K23;0;A1;5.0
G45A;1;A11;0;B1;5.0

usortm report

Generate final report and plate maps.

usortm report my_project/

Options

Option Short Description Default
--format -f Output format (csv, html, json, all) all

Output Files

my_project/report/
├── summary.html          # Interactive HTML report
├── plate_maps.csv        # Source and target assignments
├── final_mapping.csv     # Variant to well mapping
└── missing_variants.csv  # Unrecovered variants

JSON Output

Several commands support --json output for programmatic use:

usortm estimate -n 500 -l 300 --fold-sampling 8 --json | jq '.costs.total'

Example JSON output:

{
  "library_size": 500,
  "seq_length": 300,
  "fold_sampling": 8.0,
  "costs": {
    "synthesis": 1373.33,
    "cloning": 53.60,
    "sorting": 117.00,
    "barcoding": 977.30,
    "sequencing": 500.00,
    "hitpicking": 79.68,
    "total": 3100.91
  },
  "effort": {
    "total_wells": 4000,
    "n_plates": 10,
    "sort_hours": 1.8,
    "sort_days": 1.0,
    "barcode_hours": 8.3,
    "barcode_days": 1.0
  }
}