Command-Line Interface

The package installs a pleb command that wraps the main pipeline. It accepts a configuration file plus optional overrides. For a list of all options, run:

pleb --help

Core usage

Run the pipeline from a config file:

pleb --config pipeline.toml

Override config values in place:

pleb --config pipeline.toml --set results_dir=\"results\" --set jobs=8

UX wrapper cheat sheet

For the single-file UX layer (pleb.toml), use:

Command

Typical use

Example

pleb init

Create starter UX config

pleb init --config pleb.toml

pleb profile list

List available presets

pleb profile list

pleb profile use <name>

Merge preset into UX config

pleb profile use balanced --config pleb.toml

pleb doctor

Validate resolved essentials

pleb doctor --config pleb.toml

pleb explain

Show UX->legacy mapping summary

pleb explain --config pleb.toml

pleb run

Execute selected mode via UX config

pleb run --config pleb.toml --set run.mode=\"pipeline\"

See UX Wrapper (Single-File Interface) for full UX-wrapper documentation.

CLI overrides (1:1 with TOML)

Any key from the TOML config can be supplied directly as a CLI flag and will override the file value. These are equivalent:

pleb --config pipeline.toml --jobs 8 --run_fix_dataset
pleb --config pipeline.toml --set jobs=8 --set run_fix_dataset=true

Boolean keys accept --key (true) and --no-key (false).

Common options

The most-used flags map directly to pleb.config.PipelineConfig:

  • --results-dir and --outdir-name for output organization.

  • --force-rerun and --no-tempo2 to control tempo2 execution.

  • --no-change-reports and --testing to skip report generation.

  • --jobs for parallel processing.

Quality-control (QC) flags

If you have optional QC dependencies installed, you can enable them with:

pleb --config pipeline.toml --qc

QC options allow you to control feature extraction and structure tests, for example:

pleb --config pipeline.toml --qc \\
  --qc-backend-col group \\
  --qc-add-orbital-phase \\
  --qc-structure-mode both

Parameter scan

To compare candidate timing-model parameters, run the param-scan mode:

pleb --config pipeline.toml --param-scan --scan F2 --scan \"JUMP -sys P200 0 1\"

The --scan-typical option applies a built-in profile that explores parallax, binary derivatives, or DM derivatives based on the timing model and reduced chi-square thresholds. [Edwards2006] [Hobbs2006]

Param-check mode (fit-only scans)

The --param-scan mode is the “param_check” workflow: it performs fit-only scans of candidate parameters without running the full pipeline. It runs tempo2 on temporary .par variants and records how the fit statistics change.

Prerequisites:

  • tempo2 available in your container/environment

  • a clean Git repo (the scan checks out branches)

  • home_dir, dataset_name, and results_dir set (via config or --set)

Outputs:

  • A standalone run directory under <results>/<outdir>_param_scan/

  • Per-pulsar scan tables in param_scan/

  • PLK logs under plk/

  • Scratch workspace under work/ (removed if cleanup_work_dir=true)

Interpreting outputs:

  • The per-pulsar tables list each candidate and the change in fit metrics (e.g., reduced chi-square or log-likelihood proxies derived from PLK logs).

  • Prefer candidates that improve fit quality without inflating uncertainties.

  • If multiple candidates improve the fit similarly, prioritize those with physical motivation (e.g., DM derivatives for dispersive trends, BTX derivatives for binary timing) and check residual structure.

QC report subcommand

If you already ran QC, you can generate report plots from a run directory:

pleb qc-report --run-dir results/run_2024-01-01

Ingest subcommand

Run mapping-driven ingest:

pleb ingest --mapping configs/catalogs/system_flags/system_flag_mapping.example.json \
  --output-dir /data/pulsars

Workflow subcommand

Run a workflow file (TOML or JSON) with steps and loops:

pleb workflow --file configs/workflows/example_iterative.toml

Public-release compare subcommand

Download latest public releases (NANOGrav, EPTA, IPTA) and compare parfile parameter values/errors:

pleb compare-public --out-dir results/public_release_compare

Optional provider catalog override:

pleb compare-public --out-dir results/public_release_compare \
  --providers configs/catalogs/public_releases/providers.toml

Optional shared cache override:

pleb compare-public --out-dir results/public_release_compare \
  --cache-dir /work/git_projects/pleb/public_release_cache

Outputs include:

  • resolved assets table

  • raw parsed parameter table

  • astrometry-normalized parameter table (ICRS/common units)

  • provider spread comparison summary

See Running Pleb for detailed compatibility notes and workflow examples, and Examples for end-to-end runs.