Dust Module (brutus.dust)

The dust module provides tools for working with 3D dust maps, including coordinate transformations and dust extinction queries.

Dust Maps

class brutus.dust.DustMap

Bases: object

Base class for querying 3D dust maps.

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

__init__()

Initialize the dust map.

__call__(coords, **kwargs)

Convenience method for querying the map.

This is an alias for the query method.

Parameters:

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

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

Return type:

Query results as implemented by subclasses.

query(coords, **kwargs)

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)

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)

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.

• frame (str, optional) – Coordinate frame. Options: ‘icrs’, ‘fk4’, ‘fk5’, ‘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)

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)

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.

get_query_size(coords)

Estimate the total size of a query result.

Parameters:

coords (astropy.coordinates.SkyCoord) – Coordinates that would be queried.

Returns:

Estimated total number of data points that would be returned.

Return type:

int

query(coords, apply_reliability_mask=None)

Query extinction at the specified coordinates.

Parameters:

• coords (astropy.coordinates.SkyCoord or array_like) – Coordinates to query. Can be a (scalar or array) SkyCoord, a single [l, b] pair in degrees, or an (Ncoords, 2) array of [l, b] pairs in degrees.

• apply_reliability_mask (bool, optional) – Whether to set extinction values flagged as unreliable by the map (distance bins outside a pixel’s reliable range, and non-converged pixels) to NaN. If None (default), uses the value set at construction (which defaults to True).

Returns:

• distances (ndarray) – Distance grid points (kpc).

• av_mean (ndarray) – Mean A(V) extinction values along each line of sight. Shape is (n_dist,) for a scalar SkyCoord or a single [l, b] pair, and (Ncoords, n_dist) for array input.

• av_std (ndarray) – Standard deviation of A(V) extinction values (same shape as av_mean).

Notes

For coordinates outside the map coverage, NaN values are returned. With reliability masking active (the default), NaN is also returned for distance bins outside a pixel’s reliable distance-modulus range and for pixels whose fits did not converge; ~brutus.priors.extinction.logp_extinction treats NaN as “no coverage” and falls back to a uniform prior there.

Submodules

For advanced users who need access to internal implementations:

3D dust map implementations.

This module provides classes for querying 3D dust maps, particularly the Bayestar maps from Green et al. (2019).

class brutus.dust.maps.DustMap

Bases: object

Base class for querying 3D dust maps.

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

__init__()

Initialize the dust map.

__call__(coords, **kwargs)

Convenience method for querying the map.

This is an alias for the query method.

Parameters:

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

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

Return type:

Query results as implemented by subclasses.

query(coords, **kwargs)

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)

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)

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.

• frame (str, optional) – Coordinate frame. Options: ‘icrs’, ‘fk4’, ‘fk5’, ‘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.maps.Bayestar(dustfile='bayestar2019_v1.h5', apply_reliability_mask=True)

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)

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.

get_query_size(coords)

Estimate the total size of a query result.

Parameters:

coords (astropy.coordinates.SkyCoord) – Coordinates that would be queried.

Returns:

Estimated total number of data points that would be returned.

Return type:

int

query(coords, apply_reliability_mask=None)

Query extinction at the specified coordinates.

Parameters:

• coords (astropy.coordinates.SkyCoord or array_like) – Coordinates to query. Can be a (scalar or array) SkyCoord, a single [l, b] pair in degrees, or an (Ncoords, 2) array of [l, b] pairs in degrees.

• apply_reliability_mask (bool, optional) – Whether to set extinction values flagged as unreliable by the map (distance bins outside a pixel’s reliable range, and non-converged pixels) to NaN. If None (default), uses the value set at construction (which defaults to True).

Returns:

• distances (ndarray) – Distance grid points (kpc).

• av_mean (ndarray) – Mean A(V) extinction values along each line of sight. Shape is (n_dist,) for a scalar SkyCoord or a single [l, b] pair, and (Ncoords, n_dist) for array input.

• av_std (ndarray) – Standard deviation of A(V) extinction values (same shape as av_mean).

Notes

For coordinates outside the map coverage, NaN values are returned. With reliability masking active (the default), NaN is also returned for distance bins outside a pixel’s reliable distance-modulus range and for pixels whose fits did not converge; ~brutus.priors.extinction.logp_extinction treats NaN as “no coverage” and falls back to a uniform prior there.

Extinction and coordinate utilities for dust mapping.

This module provides utilities for coordinate transformations and extinction calculations used in 3D dust mapping.

brutus.dust.extinction.lb2pix(nside, l, b, nest=True)

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

Parameters:

• nside (int) – The HEALPix nside 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) – Whether to use nested pixel ordering instead of ring ordering. Default is True.

Returns:

pix_ids – HEALPix pixel indices corresponding to the input (l, b) coordinates. Invalid coordinates (absolute b > 90°) return -1.

Return type:

int or ndarray

Examples

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

>>> # Multiple coordinates
>>> 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)
>>> len(pix_arr) == 3
True

>>> # Invalid coordinate
>>> invalid_pix = lb2pix(nside=64, l=0.0, b=95.0)
>>> invalid_pix == -1
True