CLI Reference#

calibrate#

Main calibration binary.

calibrate [OPTIONS] [COMMAND]

Default Mode (Calibration)#

Flag

Default

Description

-i, --input <PATH>

L0 Zarr store path

--output <PATH>

L1 Zarr output directory

--atm-table <PATH>

ATM table file (.catm, .dat, or .dat.gz)

--manifest <PATH>

WFM manifest JSON (replaces –input/–output/–atm-table)

--pwv <FLOAT>

fit

Fixed PWV in mm (omit to fit from data)

--mode <MODE>

auto

Observation mode: auto, tp, otf, otf-chopped

--list-scans

List scans in the input store and exit (no calibration)

--scan-range <START> <END>

Only calibrate scans in range [START, END] inclusive

--threads <N>

auto

Rayon thread pool size

-v, --verbose

Increase log level (-v = debug, -vv = trace)

-q, --quiet

Suppress progress bar

Instrument Parameters#

Flag

Default

Description

--forward-eff (alias: --foeff)

0.97

Forward efficiency eta_f [0.0–1.0]

--sideband-gain (alias: --gain-image)

0.5

Image sideband gain [0.0–1.0]; signal gain = 1 - this

--physics <MODE>

kalibrate-compat

Physics constants: exact, kalibrate-compat

Advanced Calibration#

Flag

Default

Description

--pwv-per-pixel

false

Fit PWV independently per pixel

--dbs-coupling (alias: --dbs-adhesive)

false

Enable dual-beam-switch coupling (cross-beam OFF averaging + A+B merge)

--gain-interpolate <LEVEL>

0

Gain drift correction [0=off, 2=correct ON, 3=correct ON+OFF]

--skydiff <N>

0

SKY-DIFF diagnostic depth [0=off, N=diff against N most recent OFFs]

--skychopdiff

false

SKYCHOPDIFF diagnostic: chop-phase diffs of the sky in chopped scans

FITS Ingest Mode (requires fits-ingest feature)#

Flag

Default

Description

-f, --fits-folder <PATH>

FITS folder to convert and calibrate

--zarr-cache <PATH>

<fits_folder>.zarr

Where to place the converted Zarr store

Subcommands#

calibrate convert

Convert a text ATM table to binary format for fast loading.

calibrate convert --input atm.dat.gz --output atm.catm

Exit Codes#

  • 0 – all scans calibrated successfully

  • 1 – all scans failed (or no scans found)

  • 2 – partial failure (some scans succeeded, see failures.json)

Manifest Schema#

{
  "input_zarr_paths": ["/data/l0/session.zarr"],
  "atm_table_path": "/data/atm/atm.catm",
  "output_dir": "/data/l1/",
  "scan_range": [25650, 25660],
  "config_overrides": {
    "obs_mode": "otf",
    "pwv": 1.2,
    "physics": "exact",
    "foeff": 0.97,
    "gain_image": 0.5,
    "threads": 8
  }
}

All config_overrides values are validated at startup: an unknown obs_mode or physics string, an efficiency/gain outside [0.0, 1.0], or a non-positive pwv is a fatal error (exit 1). Invalid overrides never fall back silently to CLI defaults. The same bounds are enforced on the corresponding CLI flags.

zarr-fits#

Standalone FITS-to-Zarr conversion binary.

zarr-fits convert [OPTIONS]

Flag

Default

Description

-f, --fits-folder <PATH>

Input directory containing FITS files

-z, --zarr-path <PATH>

Output Zarr store path

-s, --scans <RANGE>

Scan filter (e.g., 100,200 for range or 100,200,300 for list)

-w, --workers <N>

CPU count

Parallel worker threads

--overwrite

false

Re-process scans already in store

-p, --profile <NAME>

auto

Telescope profile name

--profiles-dir <PATH>

embedded

Custom profile directory

-v

Verbosity (-v = debug, -vv = trace)

Examples#

# Basic calibration
calibrate -i session.zarr --output l1/ --atm-table atm.catm

# OTF mode with fixed PWV
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --pwv 1.2 --mode otf

# Custom instrument parameters (new flag names)
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --forward-eff 0.95 --sideband-gain 0.45

# Gain interpolation with per-pixel PWV
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --gain-interpolate 2 --pwv-per-pixel

# SKYDIFF diagnostic (diff against 3 most recent OFFs)
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --skydiff 3

# SKYDIFF + SKYCHOPDIFF on chopped data, kalibrate-comparison trim
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --physics kalibrate-compat --foeff 0.97 \
  --skydiff 3 --skychopdiff --dbs-coupling

# List scans without calibrating
calibrate -i session.zarr --list-scans

# Calibrate a specific scan range
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --scan-range 25650 25660

# FITS folder -> convert + calibrate
calibrate -f /data/raw/session_001 --output l1/ --atm-table atm.catm

# Standalone conversion
zarr-fits convert -f /data/raw/session_001 -z session.zarr

# Convert ATM table to binary
calibrate convert --input atm.dat.gz --output atm.catm

# Batch via manifest
calibrate --manifest manifest.json