Dust Module (brutus.dust)

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[source]#

Bases: object

Base class for querying 3D dust maps.

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

__init__()[source]#

Initialize the dust map.

__call__(coords, **kwargs)[source]#

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)[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.

  • 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')[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’.

_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

__init__(dustfile='bayestar2019_v1.h5')[source]#

Initialize the Bayestar dust map.

Parameters:

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

get_query_size(coords)[source]#

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)[source]#

Query extinction at the specified coordinates.

Parameters:

coords (astropy.coordinates.SkyCoord) – Coordinates to query. Can be single coordinate or array.

Returns:

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

  • av_mean (ndarray) – Mean A(V) extinction values along each line of sight.

  • av_std (ndarray) – Standard deviation of A(V) extinction values.

Notes

For coordinates outside the map coverage, NaN values are returned.

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[source]

Bases: object

Base class for querying 3D dust maps.

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

__init__()[source]

Initialize the dust map.

__call__(coords, **kwargs)[source]

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)[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.

  • 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')[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’.

_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

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

Initialize the Bayestar dust map.

Parameters:

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

get_query_size(coords)[source]

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)[source]

Query extinction at the specified coordinates.

Parameters:

coords (astropy.coordinates.SkyCoord) – Coordinates to query. Can be single coordinate or array.

Returns:

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

  • av_mean (ndarray) – Mean A(V) extinction values along each line of sight.

  • av_std (ndarray) – Standard deviation of A(V) extinction values.

Notes

For coordinates outside the map coverage, NaN values are returned.

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)[source]

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