BayesEoR operations CLI (ValSKA)

This page documents the operational helper CLIs used after sweep preparation/submission:

  • valska-bayeseor-help

  • valska-bayeseor-resume

  • valska-bayeseor-report-all

  • valska-bayeseor-compare-sweeps

  • valska-bayeseor-cleanup

These commands are intended for recovery, reporting at campaign scale, comparison of outcomes, and safe maintenance.

Naming conventions used in this page:

  • run_id: identifier stored in sweep metadata

  • sweep_dir: _sweeps/<run_id> directory containing sweep_manifest.json

  • run_dir: one per-point directory referenced by a sweep point row

0) Command index / discoverability

valska-bayeseor-help prints a concise summary of BayesEoR commands grouped by topic.

Basic usage:

valska-bayeseor-help

Filter by topic:

valska-bayeseor-help --topic reporting
valska-bayeseor-help --topic operations

Machine-readable output:

valska-bayeseor-help --json

Topics currently supported:

  • setup

  • submission

  • reporting

  • health

  • operations

1) Resume incomplete sweep points

valska-bayeseor-resume inspects one sweep and prints exact valska-bayeseor-submit commands for missing work.

Basic usage:

valska-bayeseor-resume /path/to/_sweeps/<run_id>

Generate only GPU-stage suggestions:

valska-bayeseor-resume /path/to/_sweeps/<run_id> --stage gpu

Generate only CPU-stage suggestions:

valska-bayeseor-resume /path/to/_sweeps/<run_id> --stage cpu

Machine-readable output:

valska-bayeseor-resume /path/to/_sweeps/<run_id> --json

Key behavior:

  • skips already-complete points

  • emits minimal command set needed per point

  • can include notes about missing jobs.json or detected CPU job-id hints

2) Batch reporting across discovered sweeps

valska-bayeseor-report-all discovers sweeps under results_root and runs valska-bayeseor-report logic for each selected sweep.

Default run:

valska-bayeseor-report-all

Filter by campaign dimensions:

valska-bayeseor-report-all --beam airy --sky GSM_plus_GLEAM
valska-bayeseor-report-all --run-id sweep_airy_init
valska-bayeseor-report-all --latest

Skip already-reported sweeps:

valska-bayeseor-report-all --only-new

No-plot batch mode (tables only):

valska-bayeseor-report-all --no-plots

Write reports under a separate root:

valska-bayeseor-report-all --out-root /path/to/report_mirror

JSON output and CI-friendly failure mode:

valska-bayeseor-report-all --json
valska-bayeseor-report-all --fail-on-error

Key behavior:

  • preserves per-sweep report structure and output files

  • records generated/skipped/error counts in summary payload

3) Compare two sweep outcomes

valska-bayeseor-compare-sweeps compares per-point report metrics between two sweep summaries.

Accepted input forms for each side:

  • sweep dir containing report/sweep_report_summary.json

  • report dir containing sweep_report_summary.json

  • direct path to sweep_report_summary.json

Basic usage:

valska-bayeseor-compare-sweeps /path/to/sweep_A /path/to/sweep_B

Choose comparison metric:

valska-bayeseor-compare-sweeps /path/to/A /path/to/B \
  --metric log10_bayes_factor_signal_over_no_signal

Show only top-N largest absolute deltas:

valska-bayeseor-compare-sweeps /path/to/A /path/to/B --top 20

Machine-readable output with labels:

valska-bayeseor-compare-sweeps /path/to/A /path/to/B \
  --left-name baseline --right-name trial --json

Compared metric is interpreted as right - left.

Summary includes:

  • shared / left-only / right-only point counts

  • status mismatch counts

  • compared points and skipped-missing-metric counts

  • mean/min/max delta statistics

4) Cleanup (safe-by-default maintenance)

valska-bayeseor-cleanup supports maintenance cleanup with strong safety controls.

Important defaults:

  • default mode is dry-run (no filesystem changes)

  • by default, execution uses move-to-trash mode (reversible)

  • hard deletion requires explicit --hard-delete

  • run-directory removal requires explicit confirmation token

Scope selection

Choose one or more scopes:

--prune-logs
--prune-temp
--prune-runs

or all scopes:

--all

Dry-run preview

Preview all cleanup candidates:

valska-bayeseor-cleanup --all --json

Execute log cleanup (reversible)

valska-bayeseor-cleanup --prune-logs --execute

Execute run-directory cleanup (requires confirmation)

Run cleanup for missing points only:

valska-bayeseor-cleanup \
  --prune-runs \
  --run-status missing \
  --execute \
  --confirm-runs DELETE

Optional hard-delete mode:

valska-bayeseor-cleanup \
  --prune-runs \
  --run-status missing \
  --execute \
  --confirm-runs DELETE \
  --hard-delete

Age gate:

valska-bayeseor-cleanup --prune-logs --older-than-days 14 --execute

Filtering options mirror sweep discovery tools:

  • --run-id, --beam, --sky, --latest, --max-results

CI-friendly behavior:

valska-bayeseor-cleanup --prune-logs --execute --fail-on-error

Suggested operational sequence

For large campaigns, a practical order is:

  1. valska-bayeseor-sweep-audit (health + validation overview)

  2. valska-bayeseor-resume (generate exact missing-stage commands)

  3. valska-bayeseor-report-all (refresh campaign-wide reports)

  4. valska-bayeseor-compare-sweeps (compare baseline vs trial)

  5. valska-bayeseor-cleanup (dry-run first; execute only when ready)

Wrapper scripts (bash)

Shell wrappers are available under bash_scripts/ for these commands:

  • bash_scripts/valska-bayeseor-help.sh

  • bash_scripts/valska-bayeseor-resume-sweep.sh

  • bash_scripts/valska-bayeseor-report-all.sh

  • bash_scripts/valska-bayeseor-compare-sweeps.sh

  • bash_scripts/valska-bayeseor-cleanup.sh

Each wrapper follows the same fallback order:

  1. use the CLI directly from PATH

  2. fall back to conda run -n <VALSKA_CONDA_ENV>

  3. fall back to local module execution (PYTHONPATH=src python -m ...)

Set the optional environment variable if needed:

export VALSKA_CONDA_ENV=valska

Future direction (roadmap note)

Current tooling uses separate command entry points (for example, valska-bayeseor-sweep, valska-bayeseor-report, valska-bayeseor-cleanup).

A future simplification path is to add a single root command with subcommands:

valska-bayeseor <subcommand> [...]

This is intentionally tracked as a future migration idea to preserve current stable workflows while improving discoverability and shared option handling over time.