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

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	8.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)	300
--fold-sampling	-f	Fold oversampling	8.0
--skew	-s	Expected library skew	4.0
--target-coverage		Target recovery fraction	0.90
--barcodes	-b	Barcode kit or CSV path	levseq

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

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 (column/row)	column
--unique-only/--all-hits		Pick one well per variant	True

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