Dust Module (brutus.dust)

brutus.dust queries three-dimensional interstellar dust maps on multi-resolution HEALPix grids and maps sky coordinates to HEALPix pixels.

Key Components:

  • Dust Map Interface (DustMap): Abstract base class supporting queries by astropy.coordinates.SkyCoord (query), Galactic coordinates (query_gal), or equatorial coordinates (query_equ).

  • Bayestar 3D Dust Map (Bayestar): Queries the Green et al. [2019] Bayestar19 dust map (bayestar2019_v1.h5) across the Pan-STARRS 1 footprint (\(\delta > -30^\circ\)), returning the distance grid (in kpc) and the mean and standard deviation of \(A_V\) (in mag) along each sightline while applying per-pixel convergence and distance-reliability masks by default.

  • Coordinate Lookup (lb2pix): Converts Galactic \((\ell, b)\) coordinates in degrees to nested or ring HEALPix pixel indices.

Dust Maps

class brutus.dust.DustMap[source]

Bases: object

Base class for querying 3D dust maps.

This abstract base class defines the interface that all dust map implementations should follow.

query(coords, **kwargs)[source]

Query the map at a set of coordinates.

Parameters:

  • coords (astropy.coordinates.SkyCoord) – Coordinates to query.

  • **kwargs – Additional keyword arguments.

Return type:

Query results as implemented by subclasses.

Raises:

NotImplementedError – This method must be implemented by subclasses.

query_gal(ell, b, d=None, **kwargs)[source]

Query the map using Galactic coordinates.

Parameters:

  • ell (float or astropy.units.Quantity) – Galactic longitude in degrees.

  • b (float or astropy.units.Quantity) – Galactic latitude in degrees.

  • d (float or astropy.units.Quantity, optional) – Distance from the Solar System in kpc. Not used by HEALPix-based maps but accepted for API compatibility.

  • **kwargs – Additional keyword arguments passed to query.

Return type:

Query results as implemented by subclasses.

query_equ(ra, dec, d=None, frame='icrs', **kwargs)[source]

Query the map using Equatorial coordinates.

Parameters:

  • ra (float or astropy.units.Quantity) – Right ascension in degrees.

  • dec (float or astropy.units.Quantity) – Declination in degrees.

  • d (float or astropy.units.Quantity, optional) – Distance from the Solar System in kpc. Accepted for API compatibility because the query always returns the full distance profile.

  • frame (str, optional) – Coordinate frame ('icrs', 'fk4', 'fk5', or 'fk4noeterms'). Default is 'icrs'.

  • **kwargs – Additional keyword arguments passed to query().

Return type:

Query results as implemented by subclasses.

Raises:

ValueError – If frame is not one of the supported coordinate frames.

class brutus.dust.Bayestar(dustfile='bayestar2019_v1.h5', apply_reliability_mask=True)[source]

Bases: DustMap

Query the Bayestar 3D dust maps from Green et al. (2019).

The Bayestar maps cover the Pan-STARRS 1 footprint (dec > -30°) over approximately 3/4 of the sky, providing 3D extinction information.

Parameters:

  • dustfile (str, optional) – Path to the Bayestar HDF5 data file. Default is ‘bayestar2019_v1.h5’.

  • apply_reliability_mask (bool, optional) – Whether queries mask (set to NaN) extinction values that Green et al. (2019) flag as unreliable: distance bins outside a pixel’s reliable distance-modulus range (DM_reliable_min/DM_reliable_max) and pixels whose fits did not converge (converged == 0). NaN values degrade to a uniform prior in ~brutus.priors.extinction.logp_extinction. Can be overridden per query. If the data file lacks the reliability fields, masking is skipped with a warning. Default is True.

_distances

Distance grid points (kpc).

Type:

ndarray

_av_mean

Mean A(V) extinction values.

Type:

ndarray

_av_std

Standard deviation of A(V) extinction values.

Type:

ndarray

_d_reliable_min

Per-pixel minimum reliable distance (kpc), or None if the file lacks reliability metadata.

Type:

ndarray or None

_d_reliable_max

Per-pixel maximum reliable distance (kpc), or None if the file lacks reliability metadata.

Type:

ndarray or None

_converged

Per-pixel convergence flags, or None if the file lacks reliability metadata.

Type:

ndarray or None

__init__(dustfile='bayestar2019_v1.h5', apply_reliability_mask=True)[source]

Initialize the Bayestar dust map.

Parameters:

  • dustfile (str, optional) – Path to the Bayestar HDF5 data file.

  • apply_reliability_mask (bool, optional) – Default masking behavior for queries (see class docstring). Default is True.

query(coords, apply_reliability_mask=None)[source]

Query extinction at the specified coordinates.

Parameters:

  • coords (astropy.coordinates.SkyCoord or array_like) – Coordinates to query as a scalar or array SkyCoord, a single [l, b] pair in degrees of shape (2,), or an array of [l, b] pairs in degrees of shape (Ncoords, 2). Any distance attached to coords is ignored because the full distance profile is returned.

  • apply_reliability_mask (bool, optional) – Whether to set extinction values in unreliable distance bins and non-converged pixels to NaN. If None (default), uses the value set at construction (default True).

Returns:

  • distances (numpy.ndarray) – Distance grid points in kpc of shape (n_dist,).

  • av_mean (numpy.ndarray) – Mean \(A(V)\) extinction in magnitudes along each sightline, with shape (n_dist,) for a single sightline or (Ncoords, n_dist) for array input. Preserves the storage dtype of the file (float16 for bayestar2019_v1.h5), so cast to float64 before arithmetic requiring more than 3 significant digits.

  • av_std (numpy.ndarray) – Standard deviation of \(A(V)\) in magnitudes, with the same shape and dtype as av_mean.

Raises:

ValueError – If an array coords does not have shape (2,) or (Ncoords, 2). A (2, 2) array is interpreted as two [l, b] pairs; pass separate longitude and latitude arrays to query_gal().

Notes

Coordinates outside the map footprint return NaN. When reliability masking is active (the default), distance bins outside a pixel’s reliable distance-modulus range and pixels whose fits did not converge also return NaN. logp_extinction() treats NaN bins as uninformative and falls back to the normalized uniform prior over avlim.

Coordinates

brutus.dust.lb2pix(nside, l, b, nest=True)[source]

Convert Galactic (l, b) coordinates to HEALPix pixel indices.

Parameters:

  • nside (int) – HEALPix nside resolution parameter (must be a power of 2).

  • l (float or array_like) – Galactic longitude in degrees.

  • b (float or array_like) – Galactic latitude in degrees.

  • nest (bool, optional) – If True (default), use NESTED pixel ordering; if False, use RING ordering.

Returns:

pix_ids – HEALPix pixel indices with the broadcast shape of l and b (int for scalar inputs, int64 array otherwise). Coordinates with non-finite l or b outside [-90, 90] degrees return -1.

Return type:

int or numpy.ndarray

Raises:

ValueError – If l and b cannot be broadcast to a common shape.

Examples

>>> pix = lb2pix(nside=64, l=0.0, b=0.0)
>>> isinstance(pix, int)
True

>>> l_arr = np.array([0.0, 90.0, 180.0])
>>> b_arr = np.array([0.0, 30.0, -30.0])
>>> pix_arr = lb2pix(nside=64, l=l_arr, b=b_arr)
>>> pix_arr.shape
(3,)

>>> lb2pix(nside=64, l=0.0, b=95.0)
-1