Skip to content

CLI reference

Generated from the typer application in src/inmotion/cli/ by walking the click command tree, so it lists exactly what the program accepts.

inmotion --help

Analyse results.

Cross-route interference from the concurrent_noise_path column.

Options:

  • --data (default: data/processed/dataset.csv) - Dataset CSV with concurrent_noise_path.
  • --output-dir (default: plots/interference) - Figure output directory.

Combine and plot results from multi-seed runs.

Options:

  • --results-dir (default: results) - Directory of per-seed result CSVs.
  • --output-dir (default: combined) - Where to write the combined analysis.
  • --seeds (default: 3,5,42) - Comma-separated seeds to combine.

Scrape Aveiro bus networks and build OD matrices.

Parse both networks and write the tables and OD matrices.

Options:

  • --refresh (default: False) - Re-download before parsing.
  • --quiet, -q (default: False) - Only report the summary.

Generate synthetic passenger flows and their OD matrices.

Options:

  • --scenarios, -n (default: 1) - How many scenarios to sample and generate.
  • --seed (default: 42) - Seed of the batch; scenario i uses seed+i.
  • --fleet - Bus sizes as name:capacity:count, comma separated.
  • --fleet-policy - random, cycle or demand.
  • --service (default: both) - Which days to generate: weekday, weekend or both.
  • --boardings-per-departure - Demand dial, when no daily total is set. Sampled when a batch is requested.
  • --daily-boardings - Total riders for the day, split over the network.
  • --alpha - Attraction exponent of a stop’s service. Sampled in a batch.
  • --beta - Journey-time decay, per minute. Sampled in a batch.
  • --step (default: 10) - Seconds between ground-truth instants.
  • --basemap (default: auto) - What the map draws under the flows: auto (CARTO when CARTO_API_KEY is set, the timetable’s own legs otherwise), carto-dark, carto-light, network, osm (needs the page served over HTTP) or none.
  • --sweep - JSON grid of parameters; every combination becomes a scenario.
  • --no-instants (default: False) - Skip the per-instant ground-truth table.
  • --no-map (default: False) - Skip the map and the GeoJSON files.
  • --no-cube (default: False) - Skip the origin-by-destination-by-time cube page.
  • --cube-stops (default: 60) - How many of the busiest stops the cube holds.
  • --no-replay (default: False) - Skip the single-route day replay page.
  • --out - Where to write: the scenario itself for a single run, or the directory holding one per scenario for a batch.

Download the raw BusWay pages and AveiroBus PDFs.

Options:

  • --refresh (default: False) - Re-download even when cached.

Place the stops on the map, from OpenStreetMap.

Options:

  • --bbox (default: 40.30,-8.95,41.10,-8.10) - Area to index, as south,west,north,east (default: the Aveiro district).
  • --stops - Per-stop table with lat/lon, which wins over any match.
  • --refresh (default: False) - Re-fetch the OpenStreetMap index.
  • --web (default: False) - Also ask Nominatim about the stops the local index could not place (one request a second, so this takes a while).

Draw the two most similar routes of each operator.

Options:

  • --service (default: weekday) - Which service to compare: weekday or weekend.
  • --out (default: plots/bus) - Figure output directory.
  • --no-labels (default: False) - Leave out the stop names on the ladders.

Slice the OD matrices by departure interval.

Options:

  • --window (default: 60) - Slice length in minutes.
  • --step (default: 60) - Minutes between slice starts.
  • --wide (default: False) - Also write a dense grid per operator, service and slice.
  • --out (default: data/bus/processed) - Where to write the tables.

Build and clean datasets.

Augment a dataset with noise injection and intra-class mixup.

Options:

  • --data - Dataset CSV to augment.
  • --output, -o - Destination CSV.

Audit a dataset per device and drop rows that poison training.

Options:

  • --data - Dataset CSV to audit.
  • --output - Write the cleaned CSV here.
  • --keep-shifted (default: False) - Keep device-shifted but self-consistent rows.
  • --drop-ambiguous (default: False) - Also drop samples the model rejects.
  • --ambiguity-thresh (default: 0.9) - Confidence above which a wrong prediction is dropped.

Turn a raw Wavecom capture into a per-route CSV.

Options:

  • --input, -i - Raw Wavecom capture (.txt).
  • --output, -o - Destination CSV.
  • --group - label:mac1,mac2,… (repeatable).
  • --group-label - group_name:final_label (repeatable).

Merge per-route CSVs into one dataset.

Options:

  • --input, -i - Directory of per-route CSVs.
  • --output, -o - Merged dataset CSV.
  • --pattern (default: *.csv) - Glob for input files.

Dataset versions and provenance.

List recorded dataset versions, newest lineage last.

Options:

  • --json (default: False) -

Regenerate the manifest’s measured fields, or print it.

Options:

  • --write (default: False) - Rewrite data/DATASETS.json.

Print the path of a dataset version, warning when it is not trustworthy.

Arguments:

  • IDENTIFIER (required) - Dataset id or file name.

Show lineage and label provenance for one dataset version.

Arguments:

  • IDENTIFIER (required) - Dataset id or file name.

Re-check every dataset against its recorded checksum and row count.

Report on the environment and the artifact store.

Edge-quantization campaign on the wavecom routers.

Score every artifact from its own weights.

Options:

  • --artifacts-dir (default: results/edge/artifacts) - Directory of -- artifacts.
  • --tables-dir (default: results/edge/tables) - Directory for canonical CSVs.

Compute the interference statistics.

Options:

  • --tables-dir (default: results/edge/tables) - Directory for canonical CSVs.
  • --raw-dir - Raw directory (for drop counters and inference windows).

Export the artifact matrix (alias of producers).

Options:

  • --artifacts-dir (default: results/edge/artifacts) - Output directory for artifacts.
  • --models - Comma-separated models (default: contract set).
  • --producers - Comma-separated producers (default: in-house).

Run the load/latency matrix on a device.

Options:

  • --device (default: wave-router) - Device key: wave-router, wave-router-2 or local.
  • --profile (default: quick) - smoke, quick or full.
  • --backend (default: cpu) - Execution backend: cpu or gpu.
  • --engine-profile (default: balanced) - Engine profile: latency, balanced or memory.
  • --artifacts-dir (default: results/edge/artifacts) - Directory of -- artifacts.
  • --tables-dir (default: results/edge/tables) - Directory for canonical CSVs.
  • --raw-dir (default: results/edge/raw) - Directory for raw device output.
  • --binary (default: rust/target/x86_64-unknown-linux-musl/release/inmotion-infer) - Static musl runtime binary to deploy.
  • --cells - Comma-separated producer:precision cells (default: profile).
  • --reps - Override the profile’s repetitions.

Run the full campaign and write a resumable run directory.

Options:

  • --profile (default: quick) - smoke, quick or full.
  • --devices (default: wave-router) - Comma-separated device keys (wave-router,wave-router-2,local).
  • --backend (default: cpu) - Execution backend: cpu or gpu.
  • --engine-profile (default: balanced) - Engine profile: latency, balanced or memory.
  • --run-dir - Explicit run directory.
  • --results-root (default: results/edge) - Root for runs/artifacts/windows.
  • --artifacts-dir - Override the artifact directory.
  • --windows-dir - Override the windows directory.
  • --binary (default: rust/target/x86_64-unknown-linux-musl/release/inmotion-infer) - Frozen runtime binary to deploy and measure with.
  • --phases - Comma-separated phase subset (default: all).
  • --meter-file - Meter reading file.
  • --meter-cmd - Meter command.
  • --resume (default: False) - Continue an interrupted run.
  • --force (default: False) - Overwrite an existing run.

Measure the engine-profile study and write engine.csv.

Options:

  • --device (default: local) - Device key: wave-router, wave-router-2 or local.
  • --backend (default: cpu) - Execution backend: cpu or gpu.
  • --artifacts-dir (default: results/edge/artifacts) - Directory of -- artifacts.
  • --tables-dir (default: results/edge/tables) - Directory for canonical CSVs.
  • --raw-dir (default: results/edge/raw) - Directory for raw device output.
  • --binary (default: rust/target/x86_64-unknown-linux-musl/release/inmotion-infer) - Static musl runtime binary to deploy.
  • --reps (default: 2) - Repetitions per study cell.

Build the figures from the tables.

Options:

  • --tables-dir (default: results/edge/tables) - Directory for canonical CSVs.
  • --out-dir (default: results/edge/figures) - Figure output directory.
  • --formats (default: pdf,png) - Comma-separated formats: pdf,png.
  • --dpi (default: 300) - Raster resolution.

Estimate or measure energy per inference.

Options:

  • --device (default: wave-router) - Device key: wave-router, wave-router-2 or local.
  • --backend - Only this backend (default: every bench row).
  • --engine-profile - Only this engine profile (default: every row).
  • --tables-dir (default: results/edge/tables) - Directory for canonical CSVs.
  • --meter-file - Meter reading file.
  • --meter-cmd - Command that prints watts or joules.

Report what each device is and has.

Options:

  • --devices (default: wave-router,wave-router-2) - Comma-separated device keys (default: both routers).

Export the producer-aware artifact matrix.

Options:

  • --artifacts-dir (default: results/edge/artifacts) - Output directory for artifacts.
  • --models - Comma-separated models (default: contract set).
  • --producers - Comma-separated producers (default: all three).
  • --precisions - Comma-separated scheme labels (default: all).

Replay the test windows on a device and compare.

Options:

  • --device (default: wave-router) - Device key: wave-router, wave-router-2 or local.
  • --profile (default: quick) - smoke, quick or full.
  • --backend (default: cpu) - Execution backend: cpu or gpu.
  • --engine-profile (default: balanced) - Engine profile: latency, balanced or memory.
  • --artifacts-dir (default: results/edge/artifacts) - Directory of -- artifacts.
  • --windows-dir (default: results/edge/windows) - Directory of per-model windows/labels/classes.
  • --tables-dir (default: results/edge/tables) - Directory for canonical CSVs.
  • --raw-dir (default: results/edge/raw) - Directory for raw device output.
  • --binary (default: rust/target/x86_64-unknown-linux-musl/release/inmotion-infer) - Static musl runtime binary to deploy.

Summarise the tables into a markdown report.

Options:

  • --tables-dir (default: results/edge/tables) - Directory for canonical CSVs.
  • --out (default: results/edge/report.md) - Report path.

Run the ABBA interference protocol on a device.

Options:

  • --device (default: wave-router) - Device key: wave-router, wave-router-2 or local.
  • --profile (default: quick) - smoke, quick or full.
  • --backend (default: cpu) - Execution backend: cpu or gpu.
  • --engine-profile (default: balanced) - Engine profile: latency, balanced or memory.
  • --artifacts-dir (default: results/edge/artifacts) - Directory of -- artifacts.
  • --tables-dir (default: results/edge/tables) - Directory for canonical CSVs.
  • --raw-dir (default: results/edge/raw) - Directory for raw device output.
  • --binary (default: rust/target/x86_64-unknown-linux-musl/release/inmotion-infer) - Static musl runtime binary to deploy.

Write the table listings for the report.

Options:

  • --tables-dir (default: results/edge/tables) - Directory for canonical CSVs.
  • --out-dir (default: results/edge/tables-md) - Output directory.
  • --artifacts-csv - Artifact manifest for T1/T15 (default: sibling).

Export the replayed test windows and labels.

Options:

  • --windows-dir (default: results/edge/windows) - Directory of per-model windows/labels/classes.
  • --models - Comma-separated models (default: contract set).

Evaluate and combine models.

Retroactive per-class metrics for saved DL checkpoints.

Options:

  • --data (default: /home/andre/Desktop/UA/IT/inMotion/inMotion/data/processed/dataset.csv) - Dataset CSV.
  • --seed (default: 42) - Random seed.
  • --checkpoints-dir (default: models/dl) - Directory of .pt checkpoints.
  • --output-dir (default: results/dl) - Where to write the results.
  • --optuna-db - Optuna storage URL, for HPO checkpoints.
  • --no-wandb (default: False) - Disable WandB logging.

Greedy ensemble selection over existing checkpoints.

Options:

  • --data (default: /home/andre/Desktop/UA/IT/inMotion/inMotion/data/processed/dataset.csv) - Dataset CSV.
  • --seed (default: 42) - Random seed.
  • --rich (default: False) - Use the 18-channel feature set.

Permutation feature importance for the DL models.

Options:

  • --data (default: /home/andre/Desktop/UA/IT/inMotion/inMotion/data/processed/dataset.csv) - Dataset CSV.
  • --seed (default: 42) - Random seed.
  • --epochs (default: 100) - Epochs per model.
  • --patience (default: 20) - Early-stopping patience.
  • --output-dir (default: docs/icaisf/paper/images) - Figure output directory.
  • --checkpoints-dir (default: models/dl) - Directory of DL checkpoints.

OOF stacking over every model family, with calibration.

Options:

  • --data (default: /home/andre/Desktop/UA/IT/inMotion/inMotion/data/processed/dataset.csv) - Dataset CSV.
  • --seed (default: 42) - Random seed.
  • --size-frontier (default: False) - Report the ensemble-size frontier.
  • --no-tabpfn (default: False) - Exclude TabPFN.
  • --no-classical (default: False) - Exclude the classical ML members.
  • --members (default: all) - all | world | world_bestdl | best_world | best_world_bestdl
  • --output - Write the result table here.

SHAP channel attribution for the world models.

Options:

  • --checkpoint (default: backup/ts_jepa_ft_seed42.pt) - Model checkpoint to explain.
  • --data (default: /home/andre/Desktop/UA/IT/inMotion/inMotion/data/processed/dataset.csv) - Dataset CSV.
  • --model (default: ts_jepa) - Model family: t_jepa, ts_jepa, lejepa, cf_jepa or sigreg.
  • --samples (default: 50) - Number of samples to explain.
  • --nsamples (default: 150) - SHAP evaluation budget.
  • --seed (default: 42) - Random seed.
  • --output-dir (default: plots/shap) - Figure output directory.

Inspect, verify and run trained models.

Recover a checkpoint’s architecture and write a sidecar.

Use –factory to resolve structural ambiguity such as TS-JEPA versus CF-JEPA at the same width, which are indistinguishable from weights alone.

Arguments:

  • CHECKPOINT (required) - Path to a .pt checkpoint.

Options:

  • --name - Name for the adopted model.
  • --factory - Pin the architecture when ambiguous.
  • --write - Write a sidecar-tagged copy to this directory.

Show the architecture and provenance of one model.

Arguments:

  • NAME (required) - Registered model name.

Adopt every checkpoint under a directory and report what is recoverable.

Arguments:

  • DIRECTORY (required) - Directory to scan for .pt files.

Options:

  • --json (default: False) -

List every registered model.

Options:

  • --json (default: False) - Machine-readable output.

Run a trained model over a CSV of RSSI windows.

The model’s preprocessing statistics were never persisted by the original training code, so scaling is reconstructed from --reference (the same CSV the model trained on) unless a saved pipeline exists next to the weights.

Arguments:

  • NAME (required) - Registered model name.

Options:

  • --input, -i - CSV of RSSI rows.
  • --reference - CSV used to fit scaling statistics.
  • --out, -o -

Strict-load every model and check it against its recorded parameter count.

Arguments:

  • NAME (optional) - Verify one model.

Regenerate figures from saved results.

Rebuild the classical-ML figures from saved CSVs.

Options:

  • --csv - A single classification_results.csv.
  • --results-dir - A directory of result CSVs.
  • --plots-dir (default: plots) - Figure output directory.
  • --eda (default: False) - Also regenerate the EDA figures.
  • --data - Dataset CSV, needed with –eda.

Rebuild the DL figures from saved CSVs.

Options:

  • --results-csv (default: results/dl/dl_detailed_seed42.csv) - Extended DL results CSV.
  • --output-dir (default: plots/dl) - Figure output directory.
  • --eda (default: False) - Also regenerate the EDA figures.
  • --data - Dataset CSV, needed with –eda.

Quantize models and measure the cost.

Measure accuracy under quantization on dataset.csv.

Options:

  • --models - Comma-separated; default: all five world models.
  • --formats - Comma-separated; default: DEFAULT_PRECISIONS.
  • --data - Dataset CSV; default: dataset.csv.
  • --seed (default: 42) - Split seed.
  • --out (default: results/edge/tables/sweep_dataset.csv) - Where to write the results CSV.
  • --producer (default: in-house) - Measure a producer’s schemes instead of the in-house presets: in-house, torch-ao or bitsandbytes. See quantize producers.
  • --allow-unrecorded-baseline (default: False) - Accept a model with no recorded fp32 baseline, such as a checkpoint from another training run. A recorded model that has MOVED still fails.

Write a portable artifact for a non-Python runtime.

Arguments:

  • MODEL (required) - Registered model name.

Options:

  • --out, -o - Destination directory.
  • --format, -f (default: fp32) - Scheme, or fp32 for none. fp16/bf16/fp8 are cast precisions and cannot be written as artifacts.
  • --producer (default: in-house) - Which quantizer: in-house, torch-ao or bitsandbytes. inmotion quantize producers lists them; with a producer, fp32 means that producer’s own default scheme.
  • --golden (default: True) - Also write golden vectors.
  • --tol (default: 0.0002) - Parity tolerance recorded in golden.json.
  • --onnx - Also write a generic f32 ONNX graph for inmotion-onnx.

List the available quantization schemes.

List the quantizers and what the runtime can read.

Run an exported artifact with the quantized Python runtime.

Options:

  • --artifact - Artifact directory.
  • --input - Text file, one window per line.
  • --device (default: cpu) - cpu or cuda (ROCm exposes itself as cuda).
  • --backend (default: auto) - auto, onnx, torchao or bnb.
  • --compute (default: int8) - f32, int8 or q4 (4-bit MatMulNBits).
  • --cache-dir - Where converted ONNX graphs are cached.
  • --force (default: False) - Rebuild the cached graph.
  • --json (default: False) - Emit JSON.

Quantize one model and report size and error.

Arguments:

  • MODEL (required) - Registered model name.

Options:

  • --format, -f (default: int8) - Scheme, e.g. q4.

Train models.

Classical ML classifiers: EDA, CV, Optuna, importance.

Options:

  • --data (default: /home/andre/Desktop/UA/IT/inMotion/inMotion/data/processed/dataset.csv) - Dataset CSV.
  • --seed (default: 42) - Random seed.
  • --optimize (default: False) - Run the Optuna tuning stage.
  • --dashboard (default: False) - Launch optuna-dashboard after tuning.
  • --models-dir (default: models) - Model output directory.
  • --results-dir (default: results) - Results output directory.
  • --plots-dir (default: plots) - Figure output directory.

Supervised deep learning: baselines, HPO/NAS, MoE, DeepStack.

Options:

  • --data (default: /home/andre/Desktop/UA/IT/inMotion/inMotion/data/processed/dataset.csv) - Dataset CSV.
  • --seed (default: 42) - Random seed.
  • --epochs (default: 150) - Max epochs per model.
  • --trials (default: 50) - Optuna trials per study.
  • --batch-size (default: 64) - Batch size.
  • --num-gpus (default: 0) - GPUs to use; 0 = auto-detect.
  • --models-dir - Checkpoint output directory.
  • --results-dir - Results CSV directory.
  • --plots-dir - Figure output directory.
  • --wandb-project - Override the WandB project.
  • --no-wandb (default: False) - Disable WandB logging.
  • --no-optuna (default: False) - Skip HPO and NAS studies.
  • --no-moe (default: False) - Skip the mixture-of-experts phase.
  • --no-deepstack (default: False) - Skip the DeepStack phase.
  • --no-meta (default: False) - Skip the metadata-fusion phases.
  • --no-resume (default: False) - Retrain even when a checkpoint exists.

JEPA world models and SIGReg: SSL pretraining and fine-tuning.

Options:

  • --model (default: t_jepa) - t_jepa, ts_jepa, lejepa, cf_jepa, sigreg or mamba3_.
  • --data (default: /home/andre/Desktop/UA/IT/inMotion/inMotion/data/processed/dataset.csv) - Dataset CSV.
  • --seed (default: 42) - Random seed.
  • --batch-size (default: 128) - Batch size.
  • --gpu (default: 0) - GPU device index.
  • --rich-features (default: False) - Use the 18-channel feature set.
  • --pretrain-epochs (default: 300) - Stage-1 epochs.
  • --finetune-epochs (default: 50) - Stage-2 epochs.
  • --epochs (default: 150) - Epochs for directly-supervised models.
  • --patience (default: 25) - Early-stopping patience.
  • --lr (default: 0.001) - Learning rate for directly-supervised models.
  • --pretrain-lr (default: 0.0003) - Stage-1 learning rate.
  • --finetune-lr (default: 0.001) - Stage-2 learning rate.
  • --probe-cadence (default: 10) - Epochs between linear probes.
  • --probe-patience (default: 15) - Probe-based patience.
  • --checkpoint - Resume from a pretrained encoder.
  • --finetune-only (default: False) - Skip pretraining.
  • --d-model (default: 256) - Model width.
  • --nhead (default: 8) - Attention heads.
  • --num-layers (default: 4) - Transformer layers.
  • --dim-ff (default: 512) - Feed-forward width.
  • --pred-dim (default: 128) - Predictor width.
  • --pred-layers (default: 2) - Predictor depth.
  • --d-state (default: 16) - Mamba-3 state width.
  • --dropout (default: 0.2) - Dropout for the Mamba-3 hybrids.
  • --mimo-rank (default: 4) - Mamba-3 MIMO rank.
  • --num-filters (default: 192) - SIGReg convolutional filters.
  • --num-blocks (default: 3) - SIGReg residual blocks.
  • --latent-dim (default: 128) - SIGReg latent width.
  • --sigreg-lambda (default: 0.01) - SIGReg regulariser weight.
  • --hpo (default: False) - Run an Optuna study first.
  • --hpo-trials (default: 30) - Trials per study.
  • --hpo-objective (default: mcc) - mcc, efficiency or pareto.
  • --models-dir (default: models/exotic) - Checkpoint output directory.
  • --results-dir (default: results/exotic) - Results CSV directory.
  • --viz-dir (default: models/exotic/viz) - Figure output directory.
  • --no-wandb (default: False) - Disable WandB logging.
  • --wandb-project (default: inMotion-exotic-hpo) - WandB project name.

Retrain the paper’s HPO-best configurations.

Options:

  • --data (default: /home/andre/Desktop/UA/IT/inMotion/inMotion/data/processed/dataset.csv) - Dataset CSV.
  • --seed (default: 42) - Random seed.
  • --epochs (default: 150) - Epochs per model.
  • --patience (default: 20) - Early-stopping patience.
  • --models - Comma-separated subset, e.g. gru,tcn.
  • --models-dir (default: models/dl) - Checkpoint output directory.
  • --results-dir (default: results/dl) - Results output directory.

Every training, evaluation and analysis pipeline exposes the same shape: a typed RunConfig dataclass and a run(args) -> int function. The CLI builds the config from typed options, so the pipelines contain no argument parsing and can be driven from Python directly:

from inmotion.pipelines.exotic import RunConfig, run
run(RunConfig(model='ts_jepa', seed=42, pretrain_epochs=500))

The two largest pipelines are packages with one module per responsibility:

pipeline package modules
inmotion train dl inmotion.pipelines.dl
config, devices, builders, workers, pipeline
inmotion train exotic inmotion.pipelines.exotic
config, devices, data, builders, training,
hpo, hpo_jepa, hpo_sigreg, hpo_mamba3, pipeline

python -m inmotion.pipelines.<name> runs the same CLI for those packages.