Advanced Configuration

This page documents options that are less commonly changed but useful for specific use cases.

Resolution Modes

[resolution]
resolution = angular    # arcseconds (default)
# resolution = physical # target_res in parsecs, converted via distance
# resolution = native   # use the overlay beam as-is

For resolution = physical, set target_res in parsecs. HexMaps converts to arcseconds per source using its distance from target_definitions.txt.

Grid Parameters

[resolution]
pixels_per_beam = 2       # spacing = target_res / pixels_per_beam
max_rad         = auto    # "auto" derives radius from overlay footprint
NAXIS_shuff     = 200     # channels in the shuffled spectrum
CDELT_SHUFF     = 4000.0  # channel width of shuffled spectrum [m/s]

FOV Edge Erosion

Pixels near the map boundary are computed from a partial kernel and are biased. HexMaps trims these by eroding the footprint:

[masking]
fov_erosion_beams = 0.5   # trim 0.5 × beam FWHM (default)
# fov_erosion_beams = 0   # disable — keep full overlay footprint
# fov_erosion_beams = 1.0 # conservative — trim one full beam

The same erosion is applied to the hex-grid, moment maps, and FITS outputs.

Reference Line and Mask Combinations

The ref_line key controls both which lines define the primary S/N mask and how that mask is combined with any external masks.

Line selection:

ref_line = first         # first cube (default)
ref_line = 12co21        # specific named line
ref_line = all           # OR-combine all lines
ref_line = 2             # first 2 lines
ref_line = individual    # one mask per line, applied independently

Combination tokens (append to any line selection, comma-separated):

AND(input)   # AND with external input mask (use_input_mask must be true)
OR(input)    # OR  with external input mask
AND(fixed)   # AND with fixed velocity-window mask (use_fixed_vel_mask = true)
OR(fixed)    # OR  with fixed velocity-window mask

Examples:

ref_line = 12co21, AND(input)
ref_line = first, OR(fixed)
ref_line = all, AND(input), AND(fixed)

The external masks are defined in the # ---- mask ---- table and enabled by use_input_mask / use_fixed_vel_mask.

Two-level S/N mask:

SN_processing   = 2, 4   # [low_SN, high_SN] thresholds
strict_mask     = false  # if true, remove spatially isolated detections
conseq_channels = 3      # min consecutive channels for a valid mask signal

Velocity Windows

Explicit velocity windows for signal integration and noise estimation:

# ---- mask ----
vel_mask,   Signal window,  -200,  200,   km/s
noise_mask, Noise blue,    -300, -150,   km/s
noise_mask, Noise red,      150,  300,   km/s

Enable with:

[masking]
use_fixed_vel_mask   = true
use_fixed_noise_mask = true

Spectral Smoothing

[spectral]
spec_smooth        = default   # no smoothing
# spec_smooth      = overlay   # smooth to overlay spectral resolution
# spec_smooth      = 5.0       # convolve to 5.0 km/s

spec_smooth_method = binned    # recommended
# spec_smooth_method = gauss       # ±10-15% RMS bias; avoid for science
# spec_smooth_method = combined    # bin first, then Gaussian residual

Hyperfine Structure Correction

For lines with hyperfine structure (HCN, N₂H⁺, CN, CCH), HexMaps can extend the signal mask to satellite components:

[paths]
hfs_file = keys/hfs_lines.txt

[masking]
use_hfs_lines = true

Add entries for each line with hyperfine structure to hfs_lines.txt.

Database Fill Mode

To add new maps or cubes to an existing .ecsv without re-running the full pipeline:

[structure]
structure_creation = fill
fname_fill = ngc5194_hexmaps_27p0as_2025_01_01.ecsv

HexMaps opens the existing file and adds only the maps/cubes that are not yet present.