CLI Reference

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

usortm --help

Commands

usortm estimate

Quick cost and effort estimation without creating a project.

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

Coverage

Library size, skew, fold-sampling, and sorting efficiency determine how much of the library a sort recovers, so estimate simulates coverage from them and reports it with the costs. Give the fold-sampling you plan to sort and the predicted coverage follows from it:

usortm estimate -n 376 -s 2 -f 3.72

Leave --fold-sampling off instead and the fold-sampling is searched for, returning the shallowest sort that reaches --target-coverage. Either way the reported figure is the mean over 100 simulations, with the 10th–90th percentile range alongside it.

Options

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

Options

Barcode Options

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

usortm skew

Measure how unevenly the amplified library is distributed, and recommend a sorting depth from that measurement. usortm plan has to assume skew from the synthesis method because the library does not exist yet; once it does, a shallow sequencing run of the library measures it directly. 12–20k reads (e.g. Plasmidsaurus premium PCR) is ample.

usortm skew library.fastq --project my_project/

Reads are aligned to the starting variant list and counted per variant. Only minimap2 is required — not Dorado or samtools — so this runs on machines that cannot run the full demux pipeline.

Reading the output

The headline view is a histogram of log₁₀ abundance: a uniform library is a tight bell, and skew shows up as width. The fitted width σ (in log₁₀ units) is the uniformity metric, and it maps directly onto the Q90/Q10 ratio.

Two curves are drawn over the bars. The first is the fit including counting noise — what the model expects to observe at this depth — and it should track the bars; where it does not, the log-normal is a poor description of the library. The second is the underlying abundance with that noise removed. The gap between them is precisely the spread that reading the histogram at face value would mistake for skew.

Why the raw ratio overstates skew

At this depth each variant is seen only ~8–30 times. Poisson counting noise alone makes a perfectly even library measure as roughly 1.6× skewed, and a genuinely 4×-skewed library of 2000 variants measures as ~6.9×. Sorting on the raw number wastes plates. usortm skew fits a zero-inflated Poisson–log-normal model and reports the raw ratio alongside a noise-corrected estimate with a confidence interval, driving the recommendation off the corrected value.

Synthesis dropouts are estimated as a separate parameter, so variants missing from the tube are not mistaken for unevenness. This yields a coverage ceiling: sorting recovers rare variants, but nothing recovers a variant that was never synthesized, and a target above the ceiling is flagged rather than chased.

Arguments

Options

Output Files

• variant_counts.csv — reads, observed fraction, denoised fraction and rank per variant
• skew_report.json — full statistics, recommendation, and read accounting
• skew_report.html — log-abundance histogram, rank-abundance and cumulative-abundance plots, with a summary table

With --project, a measured_skew block is added to usortm_project.json. This is additive: the planning-time skew and fold_sampling are left untouched so the assumption and the measurement can be compared.

Libraries this cannot measure

If variants differ by a single codon, nanopore reads cannot be attributed to individual variants and per-variant counts would be meaningless. usortm skew checks separability before counting and refuses rather than reporting confident nonsense. Pass --force to measure anyway, understanding abundances will be smeared across near-identical variants.

Accuracy and validated range

The corrected estimate is unbiased to within a few percent up to about 8× Q90/Q10, across libraries of 300–2000 variants at 7–50 reads per variant. Above roughly 10× it reads low — about 0.85× of truth at 16× — because so much of the library falls below one expected read that the likelihood has little information about how deep the tail goes. That regime is flagged in the output and in skew_report.json as beyond_validated_range, and should be read as a lower bound on both the skew and the recommended sorting depth.

To check the measurement against a known answer, scripts/make_synthetic_library.py generates a library CSV and FASTQ with the abundances, dropouts, and per-variant read counts recorded in truth.json:

python scripts/make_synthetic_library.py /tmp/lib --library-size 400 --skew 4 --dropout 0.05
usortm skew /tmp/lib/library.fastq --variants /tmp/lib/variants.csv --output /tmp/lib/skew

Recover the realized skew it reports rather than the requested value, since a finite draw differs from the distribution it came from. Use --mode codon_scan to build the single-codon shape that the separability check refuses.

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

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

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

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

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

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

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.

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