hifast.cube Spectral Cube Regridding#

Overview#

The hifast.cube module is designed to regrid a collection of spectra (usually from multiple files) into a single 3D data cube (RA, DEC, Velocity/Frequency). It handles the spatial convolution of point-like spectral data onto a regular grid using various kernels.

Processing Workflow#

The regridding process involves several key steps. Understanding these steps will help you choose the right parameters.

  1. Input Selection The module accepts a list of HDF5 files or a glob pattern (e.g., data/*.hdf5) via the fpatterns argument. It automatically detects the data field (Flux, Ta, or Power), but you can force a specific field using -k / --key.

  2. Grid Definition (WCS) The spatial grid of the output cube is defined by the World Coordinate System (WCS).

    • Range: By default, the module calculates the bounding box of all input data. You can manually restrict the area using --ra_range and --dec_range.

    • Pixel Size: The grid spacing is controlled by --bwidth. This determines the sampling interval, which should be smaller than the beam size to properly sample the resolution (e.g., 1/3 to 1/5 of the beam FWHM). The default is 60 arcseconds.

    • Projection: The default projection is AIT (Aitoff). You can select others via -p / --proj.

      • SIN / TAN: Common tangent plane projections.

      • rCAR: A special mode of CAR. This specific configuration results in a grid where RA and DEC lines are straight and orthogonal.

      For other projections and their details, please refer to Calabretta & Greisen (2002).

    • Spectral Axis: The third axis type is set by --type3 (default: vrad). Note that velocities are always calculated from the frequency information in the input files; any existing velocity columns in the input are ignored.

  3. Convolution This is the core of the imaging process. Each spectrum contributes to nearby grid pixels based on a convolution kernel.

    • Kernel: The convolution method is set by -m / --method. The default is gaussian.

    • Beam Size: The kernel width is determined by the telescope’s beam size, specified by --beam_fwhw (default: 2.9 arcmin).

    • Cutoff Radius: To optimize performance, the convolution is limited to a specific radius, controlled by --r_cut. Spectra outside this radius from a pixel center are ignored. The default is 3 * sigma, where sigma is derived from the Gaussian FWHM (\(\sigma \approx \text{FWHM} / 2.355\)).

Beam Correction (New in v1.4)#

Note

Starting from version 1.4, the --apply_beam_correction argument is mandatory.

Convolution naturally smoothes the data, degrading the effective spatial resolution of the final cube. This parameter controls how this effect is handled, which is critical for subsequent physical analysis.

If set to True (Recommended):

  • Header Update: The BMAJ and BMIN keywords in the FITS header are updated to reflect the effective spatial resolution (convolution of the telescope beam + gridding kernel).

  • Flux Scaling: Pixel values (if in Jy/beam) are scaled up by the ratio of the beam areas \((\Omega_{effective} / \Omega_{telescope})\).

Implications for Analysis:

  1. Flux Density & Column Density: Since both the pixel values (Jy/beam) and the resolution area increase by the same factor, the Surface Brightness (Jy/sr or Kelvin) remains conserved.

    \[T_B \propto \frac{S_{\nu}}{\Omega_{beam}}\]

    This ensures that calculating Column Density (\(N_{HI}\)) or converting to Jy/pixel using the header’s BMAJ will yield correct results.

  2. Spatial Resolution & Deconvolution: Because BMAJ/ BMIN correctly records the map’s resolution, calculations involving spatial extent are accurate.

    • Deconvolution: When measuring the intrinsic size of a source (\(\theta_{source}^2 = \theta_{obs}^2 - \theta_{resolution}^2\)), using the correct BMAJ/ BMIN prevents overestimating the source size.

    • Physical Quantities: Derived quantities like dynamical mass or physical diameter will be accurate.

If set to False (or for legacy data): The header retains the original telescope beam size, and pixel values are not scaled.

  • Flux Quantities: Integrated flux measurements (e.g., total Jy of a source) are consistent with the result when set to True. This is because when set to True, both the pixel values and the beam area (used for conversion) increase by the same factor, canceling out in the flux calculation.

  • Size Quantities: The BMAJ/ BMIN in the header represents the telescope resolution, which is smaller than the actual map resolution.

# Recommended: Apply correction to ensure header and flux are correct
python -m hifast.cube ... --apply_beam_correction True

  1. Output The result is saved as a FITS file specified by --outname. If the file exists, use -f to overwrite it.

Examples#

Basic Usage Process all HDF5 files in the current directory and save to cube.fits:

python -m hifast.cube *.hdf5 --outname cube.fits

Custom Grid and Resolution Create a cube with 30-arcsecond pixels, covering a specific RA/DEC range:

python -m hifast.cube data/*.hdf5 --outname high_res.fits \
    --bwidth 30 \
    --ra_range 120 125 --dec_range 30 35

Force Overwrite If you are iterating on parameters, use -f to overwrite the output file:

python -m hifast.cube *.hdf5 --outname test.fits -f

Full Parameter Reference#

Tip

You can also view the full list of parameters and their descriptions directly in your terminal by running:

python -m hifast.cube --help

Regrid spectra into a data cube.

usage: python -m hifast.cube [-h] --outname OUTNAME [-f] [-k {flux,Ta,Power}]
                             [--polar {XX,YY,M}] [--wcs_from FILE]
                             [--ra_range MIN MAX] [--dec_range MIN MAX]
                             [--wcs_ra_center DEG] [--wcs_dec_center DEG]
                             [--range3 MIN MAX] [--type3 {vopt,vrad,freq}]
                             [--bwidth ARCSEC [ARCSEC ...]] [-p PROJ]
                             [-m {gaussian}] [--beam_fwhw ARCMIN]
                             [--gaussian_fwhw ARCMIN] --apply_beam_correction
                             BOOL [--r_cut ARCSEC] [--frac_finite_min FLOAT]
                             [--nproc INT] [--step INT] [--share_mem BOOL]
                             [--temp_dir DIR] [--use_optimized_search BOOL]
                             fpatterns [fpatterns ...]

Input/Output#

fpatterns

Input file names or pattern (e.g., “data/*.hdf5”).

--outname

Output FITS file name (full path).

-f

Overwrite the output file if it already exists.

Default: False

-k, --key

Possible choices: flux, Ta, Power

Data field to use from the input files: “flux”, “Ta”, or “Power”. Default: Auto-detected.

--polar

Possible choices: XX, YY, M

Polarization to process: “XX”, “YY”, or “M” (Merge/Average).

Default: “M”

--wcs_from, --wcs-from

Path to a FITS file to copy spatial WCS parameters (RA/DEC) from. Note: The spectral axis is NOT copied.

Grid & WCS#

--ra_range, --ra-range

RA range for the output grid [deg]. Followed by two values (min, max). Default: Derived from input files.

--dec_range, --dec-range

DEC range for the output grid [deg]. Followed by two values (min, max). Default: Derived from input files.

--wcs_ra_center, --wcs-ra-center

Manually set the CRVAL1 (RA center) in the WCS header [deg].

--wcs_dec_center, --wcs-dec-center

Manually set the CRVAL2 (DEC center) in the WCS header [deg].

--range3

Range for the third axis (velocity or frequency). Followed by two values (min, max).

--type3

Possible choices: vopt, vrad, freq

Type of the third axis: “vopt” (Optical Velocity), “vrad” (Radio Velocity), or “freq” (Frequency). Note: Velocity is always calculated from the frequency information in the input data; existing velocity columns in the input are ignored.

Default: “vrad”

--bwidth

Grid pixel size [arcsec]. Followed by one value (used for both RA and DEC) or two values (RA_pix, DEC_pix).

Default: [60.0]

-p, --proj

WCS projection type. Common options: “SIN”, “TAN”, “CAR”, etc. See arXiv:astro-ph/0207413. Special mode: “rCAR” forces a Plate Carree projection resulting in straight and orthogonal RA/DEC lines.

Default: “AIT”

Convolution#

-m, --method

Possible choices: gaussian

Convolution kernel type. Currently only “gaussian” is fully supported.

Default: “gaussian”

--beam_fwhw, --beam-fwhw

Beam Full Width at Half Maximum (FWHM) [arcmin].

Default: 2.9

--gaussian_fwhw, --gaussian-fwhw

FWHM of the Gaussian convolution kernel [arcmin]. Default: beam_fwhw / 2.

--apply_beam_correction, --apply-beam-correction

Possible choices: True, False

Apply beam correction. This updates BMAJ/BMIN in the header to reflect the new effective resolution and applies a flux correction factor for Jy/beam units.

--r_cut, --r-cut

Cutoff radius for the convolution kernel [arcsec]. Spectra within this radius from a grid point are included. Default (Gaussian): 3 * sigma, where sigma is derived from –gaussian_fwhw (sigma ≈ gaussian_fwhw / 2.355).

--frac_finite_min, --frac-finite-min

Minimum fraction of finite values required in a channel to produce a valid output. If the fraction is lower, the output is NaN. (requires all spectra to be valid).

Default: 1

Performance#

--nproc, -n

Number of processes to use for parallel processing.

Default: 1

--step

Number of files to process in each batch to control memory usage.

Default: 5

--share_mem, --share-mem

Possible choices: True, False

Enable shared memory for multiprocessing (Linux only). When enabled, uses /dev/shm by default.

Default: False

--temp_dir, --temp-dir

Temporary directory for multiprocessing when –share_mem is True. (fast, in-memory). If /dev/shm is too small, specify a disk directory with more space. Note: Remember to clean up residual temp files after processing.

Default: “/dev/shm”

--use_optimized_search, --use-optimized-search

Possible choices: True, False

Use optimized search_around_sky implementation for better performance. Set to False to use original astropy implementation for comparison.

Default: False