Quickstart#

Prerequisites#

Building#

# Show all available targets
make help

# Pure Zarr mode (no C dependencies)
make release

# Full build with FITS ingest (needs libcfitsio-dev)
make release-full

# Install to ~/.cargo/bin (installs both calibrate and zarr-fits binaries)
make install          # pure Zarr
make install-full     # with FITS ingest + zarr-fits binary

Running Calibration#

From a pre-converted Zarr store:

calibrate -i /data/l0/session.zarr \
          --output /data/l1/ \
          --atm-table atm.catm

From a FITS folder (requires fits-ingest feature):

calibrate -f /data/raw/session_001 \
          --output /data/l1/ \
          --atm-table atm.catm

This creates session_001.zarr alongside the FITS folder, then calibrates. On subsequent runs the conversion is skipped automatically.

Common Options#

# Fixed PWV instead of fitting
calibrate -i session.zarr --output l1/ --atm-table atm.catm --pwv 1.2

# Custom instrument parameters (new flag names with backward-compat aliases)
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --forward-eff 0.95 --sideband-gain 0.45
# Equivalent using old aliases:
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --foeff 0.95 --gain-image 0.45

# Gain interpolation level 2
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --gain-interpolate 2

# Per-pixel PWV fitting
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --pwv-per-pixel

# SKYDIFF diagnostic
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --skydiff 3

# SKYCHOPDIFF diagnostic (chopped scans; add --dbs-coupling for
# kalibrate-style blended skies)
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --skydiff 3 --skychopdiff

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

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

Standalone FITS Conversion#

zarr-fits convert \
  --fits-folder /data/raw/session_001 \
  --zarr-path /data/l0/session.zarr

Checking Output#

Read the L1 Zarr store with Python:

import zarr

store = zarr.open("/data/l1/scan_025650", mode="r")
spectra = store["spectra"][:]    # [C, D, R, A, S] antenna temperature
t_sys = store["t_sys"][:]       # [C, R, A, S] system temperature
flags = store["flags"][:]       # [C, D, R, A, S] u16 bitmask

Python Bindings#

cd crates/cal-py && maturin develop

import _cal_rs

scans = _cal_rs.list_scans("/data/l0/session.zarr")
result = _cal_rs.calibrate_store(
    input_path="/data/l0/session.zarr",
    output_path="/data/l1/",
    atm_table_path="atm.catm",
)
print(f"OK: {result['successes']}, Failed: {len(result['failures'])}")

Running Tests#

make test          # all tests (needs libcfitsio-dev)
make test-cal      # calibration tests only (no cfitsio)
make test-zarr     # FITS conversion tests only