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
merge Combine pick results from multiple sequencing rounds into a unified pick plate
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
config list List available barcode mask presets
config add Install a user barcode mask preset from a TOML file
remote * Run demux jobs on a remote server via SSH (see Remote Execution)

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
--round Sequencing round to demultiplex (1 for initial sort, 2+ for re-order rounds) 1

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
--include-cons-errors Include wells with consensus mismatches (Other Error / Silent Mutation) in the pick list False
--round -r Sequencing round to pick from (1 for initial sort, 2+ for re-order rounds) 1

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
--round Which round to report on: 1, 2, etc., or merged (after running usortm merge) 1

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

usortm merge

Combine pick results from multiple sequencing rounds into a unified pick plate. Fills gaps from earlier rounds with results from later rounds, preserving library order. Source plate IDs are prefixed with the round number (e.g. R1_3, R2_4) so the Integra ASSIST can distinguish plates from different rounds.

usortm merge my_project/

Options

Option Short Description Default
--rounds -r Comma-separated round numbers to merge (e.g. 1,2) all completed rounds
--tier Minimum quality tier (A/B/C). Use --tier '' to disable. C
--volume -v Transfer volume (µL) for Integra ASSIST output 5.0
--target-format Target plate format (96 or 384) 384
--fill-order Fill order for target plate (row or column) row

usortm reorder

Generate synthesis ordering files for dropout variants — library members that were not recovered during hit picking. Supports multiple vendor formats.

usortm reorder my_project/ --format eblocks

Options

Option Short Description Default
--format -f Ordering format: eblocks, twist, twist_oligo, or opools (prompted if omitted) interactive
--output -o Output CSV path reorder_<format>.csv
--library -l Original library CSV with full sequences (e.g. with golden gate adapters). The longest-average-length sequence column is auto-selected. None
--pool-name -p Pool name for IDT oPools format (ignored for other formats) dropout_pool
--trim-bsai Trim each sequence to 5 bp outside its flanking BsaI sites (GGTCTC / GAGACC) False

Supported Formats

  • eblocks — IDT eBlocks (96-well plate layout: Well Position, Name, Sequence)
  • twist — Twist Gene Fragments (Sequence name, Sequence)
  • twist_oligo — Twist Oligonucleotide Pools (name, sequence)
  • opools — IDT oPools (Pool name, Sequence)

usortm platemap

Regenerate the interactive demux plate map HTML from existing results without re-running demux. Useful for adjusting the color scale or regenerating after updating annotations.

usortm platemap my_project/
usortm platemap my_project/ --min-reads 50 --output my_map.html

Options

Option Short Description Default
--min-reads -m Minimum reads per well for full color on plate map 100
--output -o Output path for the plate map HTML demux_output/plate_map.html

usortm config

Manage barcode mask presets. Mask presets define the flanking sequences used for Dorado barcode demultiplexing.

usortm config list

List all available mask presets (built-in and user-installed).

usortm config list

usortm config add

Install a user preset from a TOML mask config file.

usortm config add my_mask.toml
usortm config add my_mask.toml --name custom_preset

usortm remote

Run demux jobs on a remote server via SSH. See the Remote Execution section for a full walkthrough.

Subcommand Description
remote config Configure or display SSH connection settings (--init for interactive setup)
remote verify Check that required tools (dorado, minimap2, samtools) are installed on the remote
remote demux Upload inputs and submit a demux job
remote status Check job progress (--watch for live auto-refresh)
remote log View the remote job log
remote fetch Download results (--read-data to include pileup files)
remote cancel Cancel a running job
remote list List all remote jobs with status and disk usage
remote clean Delete old remote job directories

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