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 target 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]
Reference Line and Mask Combinations
The ref_line key is a comma-separated list of tokens. All tokens are
optional except that at least one line-selection or external-mask token must
be present.
Line-selection tokens (choose exactly one):
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
External-mask tokens (append to any line selection):
input # include the input_mask defined in the mask table
window # include the window_mask defined in the mask table
Combinator token (default OR):
OR # a sightline passes if it passes ANY mask (default)
AND # a sightline passes only if it passes ALL masks
Examples:
ref_line = 12co21, input, AND # 12co21 S/N mask AND input mask
ref_line = first, window, AND # first-line mask AND velocity window
ref_line = all, input, window # OR of all-line + input + window masks
ref_line = individual, input # per-line S/N mask OR input mask
The external masks (input_mask, window_mask) must be defined in the
# ---- mask ---- table of config.txt.
Two-level S/N mask:
SN_processing = 2, 4 # [low_SN, high_SN] thresholds
strict_mask = false # false | strict | broad
conseq_channels = 3 # min consecutive channels for a valid detection
Strict and Broad Mask Modes
Warning
The strict and broad options for strict_mask are experimental
and have not been thoroughly tested across a wide range of datasets.
Use the default value (false) unless you have a specific reason to
apply a coherence filter. If you do use strict or broad, treat
the results with care and validate them against your expectations for the
source structure and noise level.
The strict_mask key controls an optional post-processing coherence filter:
false— no additional spatial filtering (default)strict— remove connected components smaller than approximately one beam area per channel. Analogous to the ACES beam-area pruning step; suppresses isolated noise spikes while preserving spatially extended emission.broad— re-derive the mask from a spatially smoothed cube using a two-level S/N dilation strategy (core mask at high S/N, grown into a wing mask at low S/N), following the PHANGS-ALMA broad-mask approach. More inclusive than the raw S/N mask; better suited for faint extended emission.
strict_mask = false # no filter
strict_mask = strict # beam-area pruning
strict_mask = broad # smoothed-cube two-level dilation
Velocity Windows
Explicit velocity windows for signal integration and noise estimation are
defined in the # ---- mask ---- table:
# ---- mask ----
window_mask = window_mask, Fixed velocity window, -200, 200, km/s
noise_mask = noise_mask, Noise blue, -300, -150, km/s
noise_mask = noise_mask, Noise red, 150, 300, km/s
To use the velocity window for signal integration, add window to
ref_line:
ref_line = first, window, AND # first-line S/N mask AND velocity window
To use fixed noise windows for RMS estimation instead of channels outside the signal mask:
[masking]
use_fixed_noise_mask = true
Noise Mask Overlap Check
When use_fixed_noise_mask = true, the pipeline automatically removes
any channels from the noise window that overlap with the signal integration
mask before computing per-sightline RMS. This prevents signal contamination
of the noise estimate even when the noise windows are defined broadly.
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.
When use_hfs_lines = true:
In combined mode: the master mask is extended to each HFS-capable line’s satellite frequencies after it is built, producing a per-line mask stored as
SPEC_MASK_<LINE>. Moments for each line are computed using its own extended mask.In individual mode (
ref_line = individual): the per-line S/N mask already finds the satellite emission by construction, so no additional HFS extension is applied to it. External masks (input,window) are still extended to the satellite frequencies before combining.
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.
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.