soltool — gain solution management¶
soltool manages DP3 gain solution files (H5Parm format). It covers the
full post-calibration workflow: combining per-spectral-window bandpass
solutions, smoothing in time and frequency, and producing diagnostic plots.
combine — merge per-spectral-window bandpass solutions¶
combine assembles multiple H5Parm gain files into a single broadband
solution. It handles two cases automatically:
Same frequency axis — files are averaged in time using complex-space sigma-clipping. Outlier time slots (by per-antenna standard deviation and flag count) are rejected before averaging. This is the typical use case when each spectral window was calibrated independently on the same calibrator observation.
Different frequency axes — files are sorted by frequency and concatenated. All groups must share the same antenna set.
Both cases can occur in the same call: files are first grouped by frequency axis, each group is averaged, and the averaged groups are then concatenated.
Usage¶
soltool combine SW*/instrument_di_bp.h5 -o bp_cal.h5
Collects one H5Parm per spectral window (each a different frequency range),
averages time slots within each window, and concatenates across windows into
bp_cal.h5. Add --plot-dir plots/ to also write spectra.pdf and
delay.pdf alongside the output.
If instead all inputs share the same frequency axis — e.g. several calibrator
passes of the same field — combine reduces them to a single time-averaged
solution, giving a more stable bandpass:
soltool combine obs1/instrument_di_bp.h5 obs2/instrument_di_bp.h5 -o bp_cal_mean.h5
Reference¶
soltool combine¶
Combine multiple H5Parm solution files into a single file.
Files sharing the same frequency axis are averaged in time (with per-antenna sigma-clipping of outlier time slots). Files with non-overlapping frequency ranges are sorted and concatenated in frequency.
Typical use: combine per-spectral-window bandpass solutions from a NenuFAR calibrator observation.
soltool combine SW*/instrument_di_bp.h5 -o bp_cal.h5 -p plots/
Usage
soltool combine [OPTIONS] [SOLS]...
Options
- -o, --output <output>¶
Required Output H5Parm file
- -p, --plot-dir <plot_dir>¶
Write diagnostic spectrum and delay plots here
Arguments
- SOLS¶
Optional argument(s)
smooth — Gaussian smoothing in time and frequency¶
smooth applies a 2-D Gaussian kernel to the amplitude and phase of one or
more gain solution files. It operates in-place: the smoothed values are
written back into the same H5Parm file.
The kernel size is expressed as a full-width at half-maximum (FWHM) in
minutes (time axis) and MHz (frequency axis). A separate, typically larger,
kernel is used for the direction named Main (the target field) to reflect
the expectation that the main-field solutions vary more slowly than bright
off-axis sources.
Phase smoothing is done in the complex plane (exp(i·phase)) to avoid
wrapping artefacts near ±π. Flagged samples (stored as NaN) are excluded
from the convolution via a masked-array boundary extension.
Amplitude outliers are sigma-clipped at --clip_nsigma before smoothing so
that a single bad solution does not spread into its neighbours.
Usage¶
soltool smooth instrument_di.h5
Applies a 16 min × 2 MHz kernel to all directions except Main, and a
20 min × 4 MHz kernel to Main. Tighten the kernels for a
direction-dependent solution:
soltool smooth instrument_dde.h5 --fwhm_time 8 --fwhm_freq 1 --main_fwhm_time 12 --main_fwhm_freq 2
Several files can be passed at once (each smoothed independently), and
--clip_nsigma (default 4) controls how aggressively amplitude outliers are
clipped before the Gaussian convolution.
Reference¶
soltool smooth¶
Smooth solutions with a Gaussian kernel
Usage
soltool smooth [OPTIONS] [SOLS]...
Options
- --fwhm_time <fwhm_time>¶
Time coherence scale (min)
- --fwhm_freq <fwhm_freq>¶
Freq coherence scale (MHz)
- --main_fwhm_time <main_fwhm_time>¶
Time coherence scale (min) for Main direction
- --main_fwhm_freq <main_fwhm_freq>¶
Freq coherence scale (MHz) for Main direction
- --clip_nsigma <clip_nsigma>¶
Clip solution above NSIGMA
- --main_name <main_name>¶
Name of the main direction
Arguments
- SOLS¶
Optional argument(s)
plot — waterfall plots per antenna¶
plot produces amplitude and phase waterfall images (time on the x-axis,
frequency on the y-axis) for every antenna in the solution file. One PNG is
written per combination of data type (amplitude or phase), calibration
direction, and polarisation.
All PNGs for a given solution file are written to a subdirectory named
sol_plots/ next to the file (configurable with --plot_dir).
Usage¶
soltool plot instrument_di.h5
Writes PNGs to instrument_di/sol_plots/, one per direction and polarisation
for both amplitude and phase. Use --plot_dir to change the output location;
multiple files can be passed in one call.
Reference¶
soltool plot¶
Plot amplitude and phase waterfalls for each direction and polarisation
Usage
soltool plot [OPTIONS] [SOLS]...
Options
- --plot_dir <plot_dir>¶
Output directory
Arguments
- SOLS¶
Optional argument(s)
plot-spectra — bandpass amplitude spectra¶
plot-spectra writes a multi-page PDF showing the bandpass amplitude as a
function of frequency for each antenna. Both polarisations are overlaid on
the same axes. The first time slot (index 0) is used, so this command is
most informative on a solution file that already has a single representative
time step — for example the output of combine.
Five antennas are shown per page by default (--nrows).
Usage¶
soltool plot-spectra bp_cal.h5
Writes bp_cal_spectra.pdf next to the input file. -o sets a custom output
path and --nrows changes how many antennas are shown per page (default 5).
Reference¶
soltool plot-spectra¶
Plot bandpass amplitude spectra per antenna to a PDF.
Usage
soltool plot-spectra [OPTIONS] SOL
Options
- -o, --output <output>¶
Output PDF (default: <sol>_spectra.pdf)
- --nrows <nrows>¶
Antennas per PDF page
Arguments
- SOL¶
Required argument
plot-delay — delay spectrum per antenna¶
plot-delay computes the Fourier transform of each antenna’s bandpass
amplitude along the frequency axis and plots the resulting delay power
spectrum. Peaks at non-zero delay reveal spectrally structured gain
errors caused by RFI, cable reflections, or calibration artefacts.
All antennas are shown in a grid on a single page. Frequencies above
--fmax (default 71 MHz, just below the FM band) are excluded before
the transform. The y-axis is logarithmic and the x-axis runs from 0 to
--delay-max microseconds.
The command requires ps_eor to be installed. If it is not available,
a warning is printed and the command exits gracefully without writing a file.
Usage¶
soltool plot-delay bp_cal.h5
Writes bp_cal_delay.pdf next to the input file. -o sets the output path,
--delay-max the x-axis range (µs), and --fmax the upper frequency cutoff —
useful when the top of the band is heavily flagged.
Reference¶
soltool plot-delay¶
Plot delay spectra per antenna to a PDF.
Usage
soltool plot-delay [OPTIONS] SOL
Options
- -o, --output <output>¶
Output PDF (default: <sol>_delay.pdf)
- --fmax <fmax>¶
Max frequency [Hz]
- --delay-max <delay_max>¶
Max delay [µs]
Arguments
- SOL¶
Required argument