CLI Reference#

PhenoTypic provides a command-line interface for batch processing plate images.

Usage#

python -m phenotypic --mode full --pipeline PIPELINE_JSON --input INPUT_DIR --output OUTPUT_DIR [OPTIONS]

Path Options#

-p, --pipeline PIPELINE_JSON

Path to a pipeline configuration file created with pipeline.to_json(). Required for full, measure, and process modes. Rejected in recompile mode, which reloads the saved pipeline from the output root.

-i, --input INPUT_DIR

Directory containing plate images to process. Required for full and process modes. Rejected in measure and recompile modes, which discover prior outputs from the output root.

-o, --output OUTPUT_DIR

Directory where results (overlays, measurements, checkpoints) are saved. Required for every mode.

Image Options#

--image-type {Image,GridImage}

Image class to use for loading. Default: Image.

--nrows N

Number of grid rows (GridImage only). Default: 8.

--ncols N

Number of grid columns (GridImage only). Default: 12.

--bit-depth {8,16}

Force bit depth. Default: auto-detect.

--detect-mode MODE

Detection matrix source channel. Default: gray.

--ext EXT

File extension filter (e.g., .png, .jpg). Default: all supported formats.

Execution Options#

-m, --mode {full,measure,recompile,process}

Select the execution mode. Default: full.

full

Apply the pipeline, measure, and emit all deliverables.

measure

Re-run measurements from HDF files in an existing output root. Requires --pipeline and --output. Rejects --input and --dry-run.

recompile

Rebuild aggregate deliverables from an existing output root. Requires --output. Rejects --pipeline, --input, and --dry-run.

process

Apply the pipeline and export one image layer per input. Requires --pipeline, --input, --output, and --layer.

--layer {rgb,gray,detect_mat,objmap}

Image layer exported by --mode process. Rejected in other modes.

--njobs N

Number of parallel worker processes. Default: all available CPUs.

--force-local

Run locally even if SLURM is available.

--dry-run

Validate pipeline and list images without processing. Supported by full and process modes; rejected by measure and recompile.

--sample N

Process only N random images (for testing).

--random-seed SEED

Random seed for --sample reproducibility.

Resume and Recovery#

--resume

Continue from a previous run. Skips already-processed images.

--retry-failures

Re-process only images that failed. Requires --resume.

--restart

Clear all state and start fresh. Mutually exclusive with --resume.

--overwrite

Reprocess all images. Mutually exclusive with --resume.

--checkpoint-interval N

Save checkpoint state every N images. Default: 100.

SLURM Options#

--slurm KEY=VALUE

Pass SLURM scheduling parameters as repeated key-value pairs (e.g., --slurm time=04:00:00 --slurm partition=gpu).

--wait

Wait for SLURM jobs to complete before returning.

Output Options#

--overlay-alpha FLOAT

Opacity of detection overlay in saved images. Default: 0.3.

--include-dataset-column

Add a dataset column to measurement CSV output.

--metadata-csv PATH

Path to a CSV file with additional metadata to merge into results.

--skip-validation

Skip pipeline validation before processing.

Tuning CLI#

PhenoTypic also ships a hyperparameter-tuning engine, python -m phenotypic.tune, which searches an ImagePipeline’s parameters to maximize a scorer. It has two subcommands: run (the search engine) and auto-space (infer a reviewable search space from a pipeline). The tpe, cmaes, gp, and nsga2 strategies require the optional tune extra (uv sync --extras tune); grid and random work out of the box.

See the tuning how-to for an end-to-end walkthrough and the distributed HPCC guide for SLURM and Postgres fan-out.

run — run a tuning spec#

python -m phenotypic.tune run SPEC_JSON -i INPUT_DIR [OPTIONS]

Path Options#

SPEC_JSON

Positional. Path to a tuning_spec.json describing the search space, scorer, and budget.

-i, --input INPUT_DIR

Directory of plate images to tune against. Required.

-o, --output OUTPUT_DIR

Directory where tuning results are written.

Search Options#

--strategy {grid,random,tpe,cmaes,gp,nsga2}

Override the spec’s strategy. grid/random use the built-in configs; tpe/cmaes/gp/nsga2 build an OptunaConfig (needs the tune extra).

--n-trials N

Trial-budget override.

--screen / --no-screen

Enable or disable the two-round screening freeze. Default: --no-screen.

Storage Options#

--storage-url URL

Optuna storage URL: sqlite:///… (local single node) or a password-less postgresql+psycopg://USER@HOST:PORT/DB (distributed; libpq reads the password from ~/.pgpass or $PGPASSWORD, so it never enters argv or the worker script). Falls back to $PHENOTYPIC_TUNE_STORAGE_URL.

Distributed Options#

--slurm

Submit a distributed worker fleet over SLURM instead of running locally.

--n-workers N

Number of SLURM array workers in the fleet (--slurm only). When unset, defaults to min(8, n_trials) (or 4 if no trial budget is known). The fleet shares the one --n-trials budget rather than multiplying it.

--slurm-partition NAME

SLURM partition for the worker fleet (--slurm only). When unset the #SBATCH --partition directive is omitted (cluster default).

--slurm-mem MEM

SLURM --mem for each worker (--slurm only), e.g. 8G.

--slurm-time HMS

SLURM --time wall-clock limit for each worker (--slurm only), e.g. 04:00:00.

Robust-Eval Options#

--held-out-fraction F

Override the spec’s held-out fraction: the target share of plates reserved for the generalization pass.

--cv-group COL

Override the held-out grouping column. When unset, the spec value (then the count scorer’s groupby[0]) is inferred.

auto-space — infer a search space#

python -m phenotypic.tune auto-space PIPELINE_JSON [OPTIONS]
PIPELINE_JSON

Positional. Path to a pipeline JSON created with pipeline.to_json().

-o, --output OUTPUT_DIR

Directory where the inferred search space is written.

--unattended

Reserved: skip the interactive review prompt (currently a no-op).