Data-cube commands

gen_vis_cube

Create a Cartesian visibility cube from frequency-dependent FITS images and matching PSF images:

$ pstool gen_vis_cube images.txt psfs.txt \
    --output_name visibilities.h5 \
    --theta_fov 4 --umin 50 --umax 250

images.txt and psfs.txt contain one FITS path per line. Both sets are sorted using their FITS CRVAL3 frequency before loading. The measured PSF images are used for the Jy/PSF normalization and weights.

The principal options control the output field of view, UV range, minimum relative weight, image window, and observing times. --int_time and --total_time accept Astropy-compatible quantities such as 10s or 10h. --use_wscnormf instead uses the FITS WSCNORMF value and does not use the PSF for normalization.

Python API. Load the output with ps_eor.datacube.CartDataCube.load(). See Data handling and the data-cube API.

even_odd_to_sum_diff

Create signal and noise-proxy cubes from compatible even and odd splits:

$ pstool even_odd_to_sum_diff even.h5 odd.h5 sum.h5 diff.h5

The outputs are (even + odd) / 2 and (even - odd) / 2. Their weights are adjusted for the two-input combination.

Python API. Both outputs are CartDataCube files and can be loaded with load(). The noise-proxy interpretation is described under Weights and noise.

diff_cube

Subtract two cubes after restricting them to their common frequency and spatial samples:

$ pstool diff_cube first.h5 second.h5 --out_file difference.h5

This is a direct difference, unlike the half-difference produced by even_odd_to_sum_diff.

Python API. Load the result with ps_eor.datacube.CartDataCube.load(); cube arithmetic and slicing are introduced in Data handling.

run_flagger

Run a configured flagger pipeline on matching Stokes-I and Stokes-V cubes:

$ pstool run_flagger stokes_i.h5 stokes_v.h5 flagger.ini \
    --output_dir flags

The command saves the combined flag as an HDF5 file and a PDF diagnostic report. It does not save new flagged data cubes; the saved flag can be applied later by another command or through the Python API.

Python API. Use ps_eor.flagger.Flag.load() followed by apply(). See Flagging and spectral filtering and the flagger API.

combine

Combine a sequence of Cartesian Stokes-I, Stokes-V, and time-difference cubes. The positional argument is a whitespace-separated table:

night_001  night_001_I.h5  night_001_V.h5  night_001_dt.h5
night_002  night_002_I.h5  night_002_V.h5  night_002_dt.h5

Run the combination with:

$ pstool combine observations.txt \
    --umin 50 --umax 250 \
    --weights_mode full \
    --output_template "combined_%STOKES%_%NUM%.h5"

%STOKES% is replaced by I, V, or dt_V and %NUM% by the number of accumulated observations. By default only the final combination is saved; --save_intermediate saves every cumulative result.

--pre_flag applies one flagger configuration to each input before combination, while --post_flag applies another to each saved combined product. --scale_with_noise rescales weights using the noise inferred from Stokes V. --inhomogeneous allows inputs that do not initially share the same complete UV sampling. --output_multi_template additionally saves the observations as a multi-night cube.

Python API. Load the combined and multi-observation outputs with ps_eor.datacube.CartDataCube.load(). The equivalent incremental API uses DataCubeCombiner; see Combining observations.

combine_sph

Combine spherical-harmonic cubes listed in the same four-column format:

$ pstool combine_sph spherical_observations.txt \
    --pre_flag flagger.ini \
    --output_template "combined_sph_%STOKES%_%NUM%.h5"

The combination uses inverse noise-variance weights estimated from the Stokes-V difference cube. --post_flag and --save_intermediate have the same roles as for combine.

Python API. Load each output with ps_eor.sphcube.SphDataCube.load(). See Spherical and wide-field analysis and the spherical-cube API.

vis_to_sph

Convert a Cartesian visibility cube to spherical-harmonic coefficients:

$ pstool vis_to_sph visibilities.h5 spherical.h5 \
    --umin 50 --umax 250 --nside 128

The command filters the requested UV range, derives lmax from the maximum retained baseline, reprojects the data, and saves a SphDataCube. If --nside is omitted, it is chosen from lmax. --flagfile applies a flag previously saved by run_flagger before the transformation.

Python API. Load the output with ps_eor.sphcube.SphDataCube.load(); filtering, imaging, and power-spectrum estimation are covered in Spherical and wide-field analysis.