Hit Picking

After demultiplexing, usortm pick generates a hit-picking list formatted for Integra ASSIST PLUS liquid handling robots. The pick list maps each recovered variant from its source plate/well to a target plate position, preserving the original library ordering.

Generating a Pick List

usortm pick my_project/

By default, one well is selected per unique variant (the well with the highest read count and consensus quality), filtered to Tier A quality (≥100 reads, >90% consensus). Wells with flanking region mismatches or consensus errors are excluded. Unrecovered variants are preserved as empty placeholders to maintain the library layout.

Options

Output Files

my_project/pick/
  Integra ASSIST Input/
    hitlist_integra_assist.csv   # Semicolon-delimited CSV for robot
    README.txt                  # Instructions for the Integra ASSIST
  pileup/
    well_1_A3.html              # Per-well pileup visualizations
    well_1_B7.html
    ...
  pick_plate_map.html           # Interactive pick plate map
  pick_list.json                # Machine-readable pick list

Integra ASSIST Format

The output CSV uses semicolon delimiters and is formatted for direct import into the Integra ASSIST PLUS software:

SampleID;SourcePlateID;SourceWell;TargetPlateID;TargetWell;TransferVolume
K44A;1;K23;0;A1;5.0
G45A;1;A11;0;A2;5.0
UNRECOVERED_X;;;;;0.0

Unrecovered variants have TransferVolume = 0, so the robot skips them while preserving the library layout on the target plate. Use --compact to omit these placeholders.

Pileup Visualizations

When --pileups is enabled (the default), a per-well HTML pileup is generated for each picked well. These show the aligned reads against the expected reference, with color-coded mismatches and insertions/deletions. Pileups are linked from the interactive pick plate map and the HTML report.

Pileup generation requires read_df.csv and per-variant reference FASTAs in the demux output. If you used remote demux, make sure to fetch with --read-data before running pick.

Streak-Out Recovery

During demux, uSort-M detects wells containing two or more correctly-assembled subpopulations of reads (streak-out candidate detection). When a variant that would otherwise be unrecovered exists as a minority population in a mixed well, usortm pick automatically adds it to the pick plate as a streakout entry.

Streakout entries appear in the pick plate map in blue and have TransferVolume = 0 in the Integra ASSIST CSV (the robot skips them). Instead, these wells should be manually streaked out to isolate the minority clone. Each streakout entry links to a per-well pileup showing the read composition.

Multi-Round Workflow

A single round of sequencing typically recovers ~85–95% of the library. Variants that were not recovered (dropouts) can be re-synthesized, re-sorted, and re-sequenced in a second round to push recovery higher. uSort-M supports this iterative loop natively.

When to Use Multiple Rounds

• Round 1 recovery is below your target (e.g. <90% for a critical library)
• You need near-complete coverage of the library for downstream assays
• Streakout alone does not recover enough missing variants

Step-by-Step

1. Export dropout variants for re-synthesis

After picking round 1, generate a synthesis order containing only the unrecovered variants:

# IDT eBlocks (96-well plate format)
usortm reorder my_project/ --format eblocks

# Twist Gene Fragments
usortm reorder my_project/ --format twist

# IDT oPools
usortm reorder my_project/ --format opools --pool-name "dropout_r2"

# Use original library sequences (with golden gate adapters)
usortm reorder my_project/ --format eblocks --library original_library.csv

The --library flag replaces dropout sequences with those from the original library CSV (e.g. with golden gate adapters or length-normalizing padding). Use --trim-bsai to trim to 5 bp outside flanking BsaI sites.

2. Plan round 2

After re-synthesis, create a round 2 plan using the dropout variants:

usortm plan dropout_variants.csv --output my_project/ --round 2

This creates a rounds/2/ subdirectory within the project with its own barcode assignments.

3. Demux and pick round 2

# Demultiplex round 2 data
usortm demux my_project/ --fastq round2.fastq --round 2

# Generate round 2 pick list
usortm pick my_project/ --round 2

4. Merge all rounds

Combine results from all rounds into a single unified pick plate:

usortm merge my_project/

merge fills gaps from earlier rounds with results from later rounds, preserving the original 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 sequencing rounds.

5. Generate the merged report

usortm report my_project/ --round merged

The merged report includes recovery curves showing cumulative variant recovery across rounds, merged plate maps, and combined detail tables.

Merge Options

Project Directory Layout

After two rounds and a merge, the project directory looks like:

my_project/
  usortm_project.json       # Master project state
  variants.csv              # Original library
  demux_output/             # Round 1 demux results
  pick/                     # Round 1 pick results
  rounds/
    2/
      usortm_round.json     # Round 2 state
      variants.csv          # Dropout variants
      demux_output/         # Round 2 demux results
      pick/                 # Round 2 pick results
  merged/
    well_assignments.csv    # Combined well assignments
    pick/
      hitlist_integra_assist.csv
      pick_plate_map.html
  report/
    summary.html            # Merged report

Generating Reports

# Single-round report
usortm report my_project/

# Report for a specific round
usortm report my_project/ --round 2

# Merged multi-round report
usortm report my_project/ --round merged

The HTML report (summary.html) includes interactive demux plate maps, pick plate maps, per-variant pileup links, and hit-picking detail tables. Open it in any browser.