HexMapsAnalysis Functions

The HexMapsAnalysis class is part of the installed hexmaps package. Instantiate it with the path to an output .ecsv file:

from hexmaps import HexMapsAnalysis

db = HexMapsAnalysis("output/ngc5194_hexmaps_27p0as_2025_01_01.ecsv")

The underlying Astropy table is available at db.struct, and the list of spectral lines at db.lines.

Coordinate Extraction

db.get_coordinates(center=None)

Return the sky coordinates of all sightlines.

Works with any coordinate system (equatorial RA/Dec, galactic GLON/GLAT, ecliptic, etc.) by reading the coordinate column names from the table.

If center is provided, coordinates are returned as offsets in arcseconds relative to that position.

Parameters:

center (str or None) – Reference coordinate string. For equatorial coordinates use sexagesimal form "13:29:52.7 47:11:43". For galactic coordinates use decimal degrees "202.47 47.19". If None, returns absolute decimal degree coordinates.

Returns:

axis1, axis2 — two 1D arrays (degrees or arcsec offsets).

Return type:

numpy.ndarray

Quicklook Plots

db.quickplot_map(line, quantity='MOM0', s=100, cmap='viridis', stretch='lin', center=None, ax=None)

Scatter plot of a moment map for line on the hexagonal grid.

Coordinate axes and x-axis inversion are set automatically based on the coordinate system of the overlay cube.

Parameters:

  • line (str) – Line name as it appears in the database, e.g. "12CO21".

  • quantity (str) – Column prefix: "MOM0", "MOM1", "MOM2", "TPEAK", "RMS", or "MAP" for a 2D map.

  • s (int) – Marker size.

  • cmap (str) – Matplotlib colormap name. Default: "viridis".

  • stretch (str) – Colour stretch: "lin", "log", or "symlog".

  • center (str or None) – If given, plot offset coordinates in arcseconds relative to this sky position.

  • ax (matplotlib.axes.Axes or None) – Existing Axes to plot into. If None, a new figure is created.

db.quickplot_spectrum(line, idx=None, show_mask=True, show_rms=True, ax=None)

Plot the spectrum at a single sightline on the native velocity grid.

Parameters:

  • line (str) – Line name, e.g. "12CO21".

  • idx (int or None) – Sightline index. If None, the sightline closest to the target centre is used.

  • show_mask (bool) – Shade the integration mask region.

  • show_rms (bool) – Overlay a horizontal line at the RMS level.

  • ax (matplotlib.axes.Axes or None) – Existing Axes to plot into.

db.quickplot_shuffled_spectrum(line, idx=None, ax=None)

Plot the velocity-shuffled spectrum at a single sightline.

Parameters:

  • line (str) – Line name.

  • idx (int or None) – Sightline index. Defaults to the sightline closest to the target centre.

  • ax (matplotlib.axes.Axes or None) – Existing Axes to plot into.

db.quickplot_radial_profile(line, quantity='MOM0', nbins=10, ax=None)

Plot a binned median radial profile of a moment map.

Requires galaxy geometry (RGAL_KPC) to be present in the table. Raises RuntimeError for non-galaxy targets.

Parameters:

  • line (str) – Line name.

  • quantity (str) – Column prefix ("MOM0", "TPEAK", etc.).

  • nbins (int) – Number of radial bins.

  • ax (matplotlib.axes.Axes or None) – Existing Axes to plot into.

Data Extraction

db.get_mom0(line)

Return the moment-0 array for line.

Parameters:

line (str) – Line name.

Returns:

1D array of integrated intensities.

Return type:

numpy.ndarray

db.get_ratio(line1, line2, sn=5.0)

Compute the line ratio line1 / line2, with upper and lower limits for sightlines where only one line is detected.

Parameters:

  • line1 (str) – Numerator line name.

  • line2 (str) – Denominator line name.

  • sn (float) – S/N threshold for detections.

Returns:

Dictionary with keys "ratio", "uc", "ulimit", "llimit".

Return type:

dict

db.get_2D_database(fname=None, save=False)

Return a copy of the table with all SPEC_* columns removed, suitable for compact storage or sharing.

Parameters:

  • fname (str or None) – Output filename. Defaults to <target>_hexmaps_2D.ecsv.

  • save (bool) – If True, write the table to fname.

Returns:

Astropy Table with spectral columns removed.

Return type:

astropy.table.Table

Provenance Recovery

db.get_config(save_to=None)

Return the full content of the config.txt that was used to produce this database, as a plain-text string.

Parameters:

save_to (str or None) – If given, write the config content to this file path.

Returns:

The original config.txt content.

Return type:

str

Example:

print(db.get_config())
db.get_config(save_to="recovered_config.txt")
db.get_log(save_to=None)

Return the full pipeline log (Loading + Regrid + Products stages) embedded in the database at run time.

Parameters:

save_to (str or None) – If given, write the log to this file path.

Returns:

The pipeline log as a plain-text string.

Return type:

str

db.list_input_headers()

List the labels of all raw FITS headers embedded in this database.

Labels correspond to the input files: e.g. "12CO21" for the SPEC_12CO21 cube, "SPIRE250" for a 2D map, "OVERLAY" for the overlay cube.

Returns:

Sorted list of label strings.

Return type:

list of str

Example:

db.list_input_headers()
# ['12CO10', '12CO21', 'OVERLAY', 'SPIRE250']
db.get_input_header(label)

Return the raw FITS header of the input file identified by label, exactly as it was on disk before any pipeline processing.

Parameters:

label (str) – Label as returned by list_input_headers(). The full metadata key (e.g. "input_header_12CO21") is also accepted.

Returns:

The original FITS header.

Return type:

astropy.io.fits.Header

Raises:

KeyError – If label is not found.

Example:

hdr = db.get_input_header("12CO21")
print(f"Native beam: {hdr['BMAJ'] * 3600:.1f} arcsec")