CLI reference

Every command, every flag, generated directly from the code at build time. Nothing on this page can drift out of date; if a flag is here, it exists.

This is a lookup table, not a tutorial. If you are designing a panel for the first time, read Getting started instead — it puts these commands in order and explains what each one is for.

The order to run them in

Step	Command	How-to
0. project	`init`	Getting started
1. dataset	`prepare` (mouse/human), `ingest` or `create-dataset` (any species)	Build a dataset
2. targets	`chkgenes`, then `convert-to-transcripts`	Choose your targets
3. codebook	`make-codebook`	Design the codebook
4. probes	`run-panel` (wraps `candidates`, `screen`, `construct`)	Design probes
5. panel QC	`filter-genes`	QC your panel
6. assembly	`check-manifest`, then `assemble short` / `assemble gen`	Order your oligos

Supporting commands, usable at any point: provenance (how was this file made?), hash (codebook identity), transcripts (one-off transcript lookup), validate-pool (check an assembled pool against the The SOLAR seqspec, before you order it) and draw-spec (draw the construct).

Things worth knowing before you read the list

--debug goes before the command name. It is an option on mkprobes itself, not on individual commands, so it is mkprobes --debug run-panel ..., never mkprobes run-panel --debug. Without it, a failure is reported as one actionable line; with it, you get the full Python traceback.

--restriction is not a free choice. It appears on screen, construct and run-panel, but SOLAR chemistry fixes the pair to BamHI + KpnI. The header/footer sequences carry those two sites and final assembly excises the probe with a KpnI/BamHI double digest, so any other pair yields probes that nothing downstream can cut out. Anything else is refused up front, with an explanation. In practice: leave the option alone.

The spelling does differ between commands, which is worth knowing when you copy a command line around:

screen and run-panel take one comma-separated value: --restriction BamHI,KpnI
construct takes a repeatable option: --restriction BamHI --restriction KpnI

assemble takes its manifest before the subcommand. The manifest is an argument on the group, because gen and short share it:

mkprobes assemble panel_a/manifest.json gen      # correct
mkprobes assemble gen panel_a/manifest.json      # wrong

The same applies to --headerfooter, which belongs to the assemble group rather than to gen. A consequence: mkprobes assemble ... gen --help still has to parse and validate the manifest first, so it needs a real one.

Which dataset a command loads is inferred from the directory. Reference datasets (prepare) and custom ones (ingest / create-dataset) are screened differently, and the difference is not cosmetic. See Which kind of dataset a command loads.

Target lists tolerate comments. Anywhere a command takes a GENES file, blank lines are skipped and everything after a # is a comment, so you can record why a target is in the panel. Listing a target twice is an error.

Every parquet output records how it was made. mkprobes provenance <file> prints the version, timestamp, command line, dataset and parameters embedded in any output parquet. The .stats.json sidecars carry the same record under a provenance key, and assemble writes a <panel>.provenance.json beside the pool.

Commands

mkprobes

Design SOLAR probe sets, from a reference to an orderable oligo pool.

The workflow is six steps, each one command:

dataset - mkprobes prepare (mouse/human) or mkprobes ingest (any species)
targets - mkprobes chkgenes, then mkprobes convert-to-transcripts
codebook - mkprobes make-codebook
probes - mkprobes run-panel (candidates, screen and construct for every target)
panel QC - mkprobes filter-genes
assembly - mkprobes assemble

Run any command with --help for its arguments. Full guide: https://www.gofflab.org/mkprobes/

Usage

mkprobes [OPTIONS] COMMAND [ARGS]...

Options

--debug: Show the full traceback when a command fails.

assemble

Turn designed probes into an orderable oligo pool.

MANIFEST is a JSON list of probe sets, each naming a codebook and the header/footer row to build against. Use gen to assemble the pool, or short first to triage targets that came up thin.

Usage

mkprobes assemble [OPTIONS] MANIFEST COMMAND [ARGS]...

Options

--headerfooter <headerfooter>: Override the splint/padlock header/footer table (default: vendored headerfooter.csv).

Arguments

MANIFEST: Required argument

gen

Usage

mkprobes assemble MANIFEST gen [OPTIONS]

Options

--rm-species <rm_species>: RepeatMasker taxon passed verbatim to -species (e.g. 'octopus', 'mollusca'). Overrides the built-in mouse/human mapping.

--skip-repeatmasker: Skip RepeatMasker explicitly (silences the no-taxon warning for non-model species).

short

Identifies and optionally removes transcripts with fewer probes than a specified threshold.

This function iterates through probe sets defined in the manifest. For each probe set, it loads the corresponding codebook and associated parquet files containing probe data. It then counts the number of probes per gene.

If the '--delete' flag is set, genes with probe counts below the 'short' threshold are removed from a copy of the .tss.txt file. If '--permanent' is also set, the original .tss.txt file is overwritten. Otherwise, a new file with the suffix '.tss.ok.txt' is created.

Args:: ctx: The Click context, containing the manifest and path. short: The minimum number of probes a gene must have. verbose: If True, prints detailed information about genes with too few probes. delete: If True, removes genes with too few probes from the .tss.txt file.
Raises:: ValueError: If genes marked for deletion are not found in the .tss.txt file.

Usage

mkprobes assemble MANIFEST short [OPTIONS] SHORT

Options

-v, --verbose

--delete: Delete the probes from a .tss.txt file that are too short.

Arguments

SHORT: Required argument

candidates

Initial screening of probes candidates for a gene.

Usage

mkprobes candidates [OPTIONS] PATH

Options

-g, --gene <gene>: Gene name

--fasta <fasta>

-o, --output <output>

-r, --ignore-revcomp

--overwrite

--pseudogene-limit <pseudogene_limit>

--allow <allow>: Don't filter out probes that bind to these genes, separated by comma.

--disallow <disallow>: DO filter out probes that bind to these genes, separated by comma.

Arguments

PATH: Required argument

check-manifest

Check a manifest before assembly spends hours proving it wrong.

Usage

mkprobes check-manifest [OPTIONS] MANIFEST

Arguments

MANIFEST: Required argument

chkgenes

Validate/check gene names (Ensembl for reference datasets; offline vs the GTF otherwise)

Usage

mkprobes chkgenes [OPTIONS] PATH GENES

Arguments

PATH: Required argument

GENES: Required argument

construct

Attach readout sequences to screened probes for one target.

Reads that target's screened probes from OUTPUT_PATH and writes <target>_final_<enzymes>_<bits>.parquet beside them.

Usage

mkprobes construct [OPTIONS] PATH OUTPUT_PATH

Options

-g, --gene <gene>: Required Target transcript to build probes for.

-c, --codebook <codebook>: Required Codebook JSON assigning readout bits to each target.

-N, --target-probes, --target_probes <target_probes>

Maximum number of probes per gene

Default:: 72

--restriction <restriction>: Restriction enzymes to exclude sites for. Repeatable.

Arguments

PATH: Required argument

OUTPUT_PATH: Required argument

convert-to-transcripts

Convert gene names to transcript IDs (canonical for reference datasets; longest/all otherwise)

Usage

mkprobes convert-to-transcripts [OPTIONS] PATH GENES

Options

-m, --mode <mode>

Options:: gencode | ensembl | canonical | appris | apprisalt | longest | all

Arguments

PATH: Required argument

GENES: Required argument

create-dataset

Build a probe-design dataset from a transcriptome FASTA.

Use this when you already have transcript sequences. To start from a genome plus an annotation instead, use mkprobes ingest, which extracts the transcripts for you.

Usage

mkprobes create-dataset [OPTIONS] PATH

Options

--fasta <fasta>

-s, --species <species>: Species name for metadata

--gtf <gtf>: Optional GTF annotation matching the FASTA. Enables gene-name lookups and transcript selection for this dataset.

--blocklist-fasta <blocklist_fasta>: FASTA of sequences to blocklist (rRNA/tRNA). Repeatable. 15-mers from these sequences are used to reject probe candidates.

--fasta-key-regex <fasta_key_regex>

Regex extracting the lookup key from FASTA headers.

Default:: '^(\\S+)'

--strip-version, --no-strip-version

Strip trailing .N version suffixes from IDs. Use --no-strip-version for de novo annotations whose IDs embed meaningful dots (StringTie STRG.1.1, AUGUSTUS g1.t1).

Default:: True

--gene-name-column <COLUMN>: Column of a registered annotation table holding the gene names you want to write in target lists, e.g. --gene-name-column Hsapiens_gene_name. Name lookup then uses only that column. Cells holding a comma-separated list count as one name per entry.

--annotation <NAME=PATH>: Register a named annotation table (parquet/csv/tsv with a transcript_id and/or gene_id column), e.g. --annotation orthologs=orthologs.tsv. Repeatable.

--overwrite: Overwrite existing dataset

Arguments

PATH: Required argument

draw-spec

Draw a seqspec as a labelled diagram of its regions.

Produces a generalized view: every region is drawn at the length it would plausibly have and labelled with its permitted range, so the picture describes the whole library rather than any one oligo. Primer binding sites read on the opposite strand are drawn pointing the other way. Needs the viz extra (pip install 'mkprobes[viz]').

Usage

mkprobes draw-spec [OPTIONS]

Options

--which <which>

Which vendored spec to draw.

Default:: 'pool'
Options:: pool | readout

--bcidx <bcidx>

Which pool spec to draw. Only the primer binding sites differ between indices.

Default:: 0

--spec <spec>: Draw this seqspec file instead of a vendored one.

-o, --out <out>: Where to write the figure. Defaults to <assay_id>.png in the working directory.

--dpi <dpi>

Default:: 200

filter-genes

Report how many probes each target ended up with, and flag the thin ones.

Counts probes in each target's _final_ output - what the target would contribute to an oligo order. Targets below --min-probes are warned about individually; rework or drop them before assembly.

Usage

mkprobes filter-genes [OPTIONS] OUTPUT_PATH

Options

-g, --genes <genes>: Required Target list to check, one per line.

--min-probes <min_probes>

Minimum number of probes per target

Default:: 48

-o, --out <out>: Write the targets that pass to this file, one per line.

Arguments

OUTPUT_PATH: Required argument

hash

Hash codebook

Usage

mkprobes hash [OPTIONS] PATH

Arguments

PATH: Required argument

ingest

Ingest a genome FASTA + GTF/GFF3 into a SOLAR probe-design dataset.

Usage

mkprobes ingest [OPTIONS] DATASET_DIR

Options

--genome <genome>: Required Genome FASTA (optionally .gz).

--gtf <annotation>: Required Annotation in GTF or GFF3 (optionally .gz). GFF3 is converted with gffread -T.

-s, --species <species>: Required Species name (metadata; not 'human'/'mouse').

--extract <extract_mode>

What gffread extracts: spliced transcripts with UTRs (-w) or CDS only (-x).

Default:: 'transcripts'
Options:: transcripts | cds

--rrna-fasta <rrna_fasta>: rRNA FASTA for the 15-mer blocklist. Repeatable.

--trna-fasta <trna_fasta>: tRNA FASTA for the 15-mer blocklist. Repeatable.

--blocklist-biotypes <blocklist_biotypes>: Comma-separated biotypes to auto-blocklist from the GTF's biotype column (e.g. 'rRNA,tRNA,snoRNA'). Requires a biotype attribute in the GTF.

--gene-name-column <COLUMN>: Column of a registered annotation table holding the gene names you want to write in target lists, e.g. --gene-name-column Hsapiens_gene_name. Name lookup then uses only that column. Cells holding a comma-separated list count as one name per entry.

--annotation-table <NAME=PATH>: Register a named annotation table (parquet/csv/tsv with transcript_id and/or gene_id column), e.g. --annotation-table orthologs=orthologs.tsv. Repeatable.

--keep-genome: Copy the genome FASTA into the dataset directory (for genome-mode simulation). Off by default: genomes are large; provenance (path+sha256) is always recorded.

--fasta-key-regex <fasta_key_regex>

FASTA header key regex.

Default:: '^(\\S+)'

--strip-version, --no-strip-version

Strip trailing .N from IDs. Default OFF for ingest: gffread headers match the GTF verbatim, and stripping merges StringTie-style isoforms (STRG.1.1/STRG.1.2).

Default:: False

--validate-only: Run validation and write the report; build nothing.

--overwrite: Overwrite existing dataset artifacts.

Arguments

DATASET_DIR: Required argument

init

Create a probe design project, ready to run.

Writes a commented target list, a valid manifest, and a README listing the commands to run in order. Edit genes.txt, then follow the README.

Usage

mkprobes init [OPTIONS] PROJECT

Options

--species <species>

Species name recorded in the manifest.

Default:: 'mouse'

--dataset <dataset>: Path to the dataset to design against. Used in the generated README.

--bcidx <bcidx>

Header/footer pair for this panel.

Default:: 0

--force: Overwrite files that already exist.

Arguments

PROJECT: Required argument

make-codebook

Generate a codebook for a target list, optionally expression-informed.

Usage

mkprobes make-codebook [OPTIONS] PATH GENES

Options

-o, --out <out>: Output JSON path (default: <genes>.codebook.json).

-e, --expression <expression_spec>: OPTIONAL: expression source for load-balanced assignment - the name of an annotation table registered in the dataset, or a parquet/csv/tsv file path. Omit for plain seeded assignment.

--expression-column <expression_column>: Value column in the expression table (needed only when ambiguous).

--n-bits <n_bits>: Code size; auto-sized from gene count if omitted.

--offset <offset>: Readout-ID offset (mutually exclusive with --existing-codebook).

--existing-codebook <existing_codebook>: Extend this codebook: derives the offset and rejects gene/bit overlap.

--iterations <iterations>

Assignments tried when --expression is given.

Default:: 200

--seed <seed>

Assignment seed (uninformed mode).

Default:: 0

Arguments

PATH: Required argument

GENES: Required argument

prepare

Prepare genomic database

Usage

mkprobes prepare [OPTIONS] PATH

Options

-s, --species <species>

Species to use for probe design

Options:: human | mouse

-t, --threads <threads>: Number of threads to use

Arguments

PATH: Required argument

provenance

Show how an output file was made: version, parameters, and dataset.

Usage

mkprobes provenance [OPTIONS] PATH

Arguments

PATH: Required argument

run-panel

Design probes for every target in CODEBOOK (candidates -> screen -> construct, in parallel).

Give an optional GENE to re-run just that target (forces overwrite for it).

Usage

mkprobes run-panel [OPTIONS] PATH CODEBOOK [GENE]

Options

-o, --output <output>: Output directory (default: <codebook dir>/output).

-j, --workers <workers>

Parallel worker processes.

Default:: 16

--allow-file <allow_file>: Per-gene acceptable off-targets JSON (default: <codebook>.acceptable.json when present).

--minimum <minimum>

Minimum probes per gene at the screen stage.

Default:: 60

--maxoverlap <maxoverlap>

Maximum probe overlap tried to reach --minimum.

Default:: 0

--restriction <restriction>

Restriction enzymes, comma-separated.

Default:: 'BamHI,KpnI'

--target-probes <target_probes>

Maximum probes per gene at the construct stage.

Default:: 48

--overwrite: Redo genes whose outputs already exist.

--list-failed: List genes without a final output, then exit.

--list-failed-all: Like --list-failed, plus each gene's top off-target counts.

Arguments

PATH: Required argument

CODEBOOK: Required argument

GENE: Optional argument

screen

Filter and tile a target's candidate probes.

OUTPUT_PATH is the directory mkprobes candidates wrote to, not your dataset: this reads <gene>_crawled.parquet from it and writes the screened set back beside it.

Usage

mkprobes screen [OPTIONS] OUTPUT_PATH GENE

Options

--fpkm-path, --fpkm_path <fpkm_path>: Expression table used to relax off-target screening against lowly expressed transcripts.

-l, --overlap <overlap>

--minimum <minimum>: Minimum number of probes per gene. Will generate probe sets with more overlaps (up to --maxoverlap) until the number is reached. Overrides --overlap.

--maxoverlap <maxoverlap>: Maximum sequence overlap between probes if minimum is set.

--restriction <restriction>: Comma-separated enzymes whose sites probes must avoid. SOLAR chemistry fixes this to BamHI,KpnI.

--overwrite: Overwrite existing files.

Arguments

OUTPUT_PATH: Required argument

GENE: Required argument

suggest-targets

Suggest panel genes that add information your current targets do not.

EXPRESSION is an AnnData (.h5ad) file with samples as rows and genes as columns. Each suggested gene is chosen to be as independent as possible of the genes already selected, so the panel spans more of the biology rather than measuring the same axis repeatedly.

Filter to informative genes first. A gene that correlates with nothing looks maximally independent to this method, so raw expression data yields suggestions that are merely noisy. Feed it highly variable genes - scanpy's highly_variable_genes is the usual route. The command warns when the output looks like this happened.

Optional. Skip it if you already know which genes you want; the output is an ordinary target list you are expected to review and edit.

Usage

mkprobes suggest-targets [OPTIONS] EXPRESSION

Options

-n, --add <n_add>: Required How many genes to suggest, on top of any you already have.

--have <have>: Targets you have already committed to, one per line. Suggestions are chosen to add information these do not already carry.

--layer <layer>: Expression layer to use. Defaults to the main matrix (adata.X).

-o, --out <out>: Write the combined target list here, ready for mkprobes chkgenes.

--score-pcs <score_pcs>

How many principal components to score the panel against. 0 to skip scoring.

Default:: 30

--n-components <n_components>: Components of the residual expression to select against. Defaults to max(--add + 20, 50). Lower it if your data has only a few distinct programmes; the choice materially changes which genes come out.

--seed <seed>

Seed for the randomized SVD, so a run is reproducible.

Default:: 42

Arguments

EXPRESSION: Required argument

transcripts

Get transcript ID from gene name or gene ID

Usage

mkprobes transcripts [OPTIONS] PATH

Options

--gene <gene>

--genefile <genefile>

--canonical: Outputs canonical transcript only (reference datasets; falls back to --longest for custom datasets)

--gencode: Outputs all transcripts from GENCODE basic

--ensembl: Outputs all transcripts from Ensembl

--appris: Outputs all principal transcripts from APPRIS (dominant coding transcripts)

--longest: Per gene, the isoform with the longest sequence (custom datasets; no network)

--all: Every isoform of each gene (custom datasets; no network)

-v, --verbose: Verbose output

Arguments

PATH: Required argument

validate-pool

Check an assembled oligo pool against the SOLAR seqspec.

POOL is a <name>_final.txt from mkprobes assemble: one oligo per line, splint and padlock alternating. Every oligo is checked for the right regions in the right order, the right total length, no KpnI or BamHI site inside the working probe, and a clamp that can actually circularise its partner. With --codebook, the readouts on each padlock are checked against the codewords that codebook assigns.

bcidx is worked out from the pool itself, so you only need to pass it to assert that a pool is the index you meant it to be.

Usage

mkprobes validate-pool [OPTIONS] POOL

Options

-c, --codebook <codebook>: Also check that every codeword in the pool is one this codebook assigns.

--bcidx <bcidx>: Header/footer pair the panel was built with (the manifest field). Detected from the pool when omitted.

--spec <spec>: Validate against this seqspec file instead of a vendored one.

--limit <limit>

Stop listing problems after this many.

Default:: 20

Arguments

POOL: Required argument

Deprecated script shims

The files under scripts/probegen/ predate the package and are kept only as shims:

Script	Replaced by
`o_codebook.py`	`mkprobes make-codebook`
`1_run_codebook*.py`	`mkprobes run-panel`
`2_assemble_manifest.py`	`mkprobes assemble`

The rest of that directory is exploratory notebooks: simulate.py (in-silico validation) and foridt.py / adt.py (IDT ordering examples whose logic already lives in the package).