tessl/pypi-dustmaps

Uniform interface for multiple dust reddening maps

Overview

Eval results

Files

3D Dust Maps

Name: tessl/pypi-dustmaps
Author: tessl

Distance-resolved extinction maps that provide dust density as a function of distance along lines of sight. These maps enable precise 3D extinction corrections, distance-dependent reddening analysis, and studies of dust distribution throughout the Milky Way.

Capabilities

Bayestar Map (Green et al. 2015, 2018, 2019)

The premier 3D dust map covering large portions of the sky with distance resolution, based on stellar photometry and parallax data.

class BayestarQuery(DustMap):
    def __init__(self, map_fname=None, max_samples=None, version='bayestar2019'):
        """
        Initialize 3D Bayestar dust map query.

        Parameters:
        - map_fname (str, optional): Path to Bayestar HDF5 file
        - max_samples (int, optional): Maximum samples to load for memory management
        - version (str): Map version ('bayestar2015', 'bayestar2017', 'bayestar2019')
        """

    def query(self, coords, mode='random_sample', return_flags=False, pct=None):
        """
        Query 3D extinction values from Bayestar map.

        Parameters:
        - coords (SkyCoord): Must include distance information
        - mode (str): Query mode ('random_sample', 'samples', 'mean', 'median', 'best')
        - return_flags (bool): Return quality flags along with extinction values
        - pct (float, optional): Percentile for percentile-based queries

        Returns:
        - float | np.ndarray: Extinction E(B-V) values
        - tuple: (extinction, flags) if return_flags=True
        """

    def query_gal(self, l, b, d, **kwargs):
        """
        Query using Galactic coordinates with distance.

        Parameters:
        - l, b (float | array): Galactic longitude, latitude (degrees)
        - d (float | array): Distance (pc)

        Returns:
        - float | np.ndarray: Extinction values
        """

class BayestarWebQuery(WebDustMap):
    def __init__(self, api_url=None, version='bayestar2019'):
        """Initialize web-based Bayestar query."""

    def query(self, coords, **kwargs):
        """Query Bayestar via web API."""

def lb2pix(nside, l, b, nest=True):
    """
    Convert Galactic coordinates to HEALPix pixel indices.

    Parameters:
    - nside (int): HEALPix resolution parameter
    - l, b (float | array): Galactic coordinates (degrees)
    - nest (bool): Use nested pixel ordering

    Returns:
    - int | np.ndarray: HEALPix pixel indices
    """

def fetch(version='bayestar2019'):
    """
    Download Bayestar map data.

    Parameters:
    - version (str): Map version to download
    """

Usage Example:

import dustmaps.bayestar
from dustmaps.bayestar import BayestarQuery
from astropy.coordinates import SkyCoord
import astropy.units as u

# Download data (first time only)
dustmaps.bayestar.fetch(version='bayestar2019')

# Initialize 3D query
bayestar = BayestarQuery(version='bayestar2019')

# Query with distance information
coord = SkyCoord(
    ra=180.0*u.deg,
    dec=30.0*u.deg,
    distance=500*u.pc,  # Distance is required for 3D maps
    frame='icrs'
)

extinction = bayestar(coord)
print(f"E(B-V) at 500 pc: {extinction:.4f}")

# Query distance-resolved extinction profile
distances = np.linspace(100, 2000, 20) * u.pc
coords_3d = SkyCoord(
    ra=180.0*u.deg,
    dec=30.0*u.deg,
    distance=distances,
    frame='icrs'
)

extinction_profile = bayestar(coords_3d)

Marshall Map (Marshall et al. 2006)

3D extinction map of the Galactic plane based on 2MASS stellar photometry, providing both extinction values and uncertainties.

class MarshallQuery(DustMap):
    def __init__(self, map_fname=None):
        """
        Initialize Marshall et al. 2006 3D map query.

        Parameters:
        - map_fname (str, optional): Path to Marshall map file
        """

    def query(self, coords, return_sigma=False):
        """
        Query 3D extinction from Marshall map (Galactic plane coverage).

        Parameters:
        - coords (SkyCoord): Coordinates with distance information
        - return_sigma (bool): Return uncertainties along with values

        Returns:
        - float | np.ndarray: A_Ks extinction values
        - tuple: (extinction, uncertainty) if return_sigma=True
        """

def fetch(clobber=False):
    """
    Download Marshall map data.

    Parameters:
    - clobber (bool): Overwrite existing files
    """

Leike & Enßlin 2019 Map

3D dust map reconstructed using Gaussian process methods from stellar observations.

class LeikeEnsslin2019Query(DustMap):
    def __init__(self, map_fname=None, **kwargs):
        """
        Initialize Leike & Enßlin 2019 3D map query.

        Parameters:
        - map_fname (str, optional): Path to L&E map file
        """

    def query(self, coords, **kwargs):
        """
        Query 3D dust density from L&E 2019 map.

        Parameters:
        - coords (SkyCoord): Coordinates with distance

        Returns:
        - float | np.ndarray: Dust density values
        """

def fetch():
    """Download Leike & Enßlin 2019 map data."""

Leike 2020 Map

Updated 3D dust map using improved Gaussian process reconstruction methods.

class Leike2020Query(DustMap):
    def __init__(self, map_fname=None, **kwargs):
        """Initialize Leike et al. 2020 3D map query."""

    def query(self, coords, **kwargs):
        """
        Query 3D dust density from Leike 2020 map.

        Parameters:
        - coords (SkyCoord): Coordinates with distance

        Returns:
        - float | np.ndarray: Dust density values
        """

def fetch():
    """Download Leike 2020 map data."""

Edenhofer 2023 Map

State-of-the-art 3D dust map using advanced Bayesian reconstruction techniques.

class Edenhofer2023Query(DustMap):
    def __init__(self, map_fname=None, **kwargs):
        """Initialize Edenhofer et al. 2023 3D map query."""

    def query(self, coords, **kwargs):
        """
        Query 3D dust density from Edenhofer 2023 map.

        Parameters:
        - coords (SkyCoord): Coordinates with distance

        Returns:
        - float | np.ndarray: Dust density values
        """

def fetch():
    """Download Edenhofer 2023 map data."""

DECaPS Map (Zucker et al. 2025)

3D dust map of the southern Galactic plane from the DECam Plane Survey.

class DECaPSQuery(DustMap):
    def __init__(self, map_fname=None, **kwargs):
        """Initialize DECaPS map query."""

    def query(self, coords, **kwargs):
        """
        Query DECaPS 3D extinction (southern Galactic plane).

        Parameters:
        - coords (SkyCoord): Coordinates with distance

        Returns:
        - float | np.ndarray: Extinction values
        """

class DECaPSQueryLite(DustMap):
    def __init__(self, map_fname=None, **kwargs):
        """Initialize lightweight DECaPS map query with reduced memory usage."""

    def query(self, coords, **kwargs):
        """Query DECaPS map with reduced memory footprint."""

def fetch():
    """Download DECaPS map data."""

Chen 2014 Map

3D extinction map focusing on specific star-forming regions and molecular clouds.

class Chen2014Query(UnstructuredDustMap):
    def __init__(self, map_fname=None):
        """Initialize Chen et al. 2014 map query."""

    def query(self, coords, **kwargs):
        """
        Query Chen 2014 3D extinction.

        Parameters:
        - coords (SkyCoord): Coordinates with distance

        Returns:
        - float | np.ndarray: Extinction values
        """

def fetch():
    """Download Chen 2014 map data."""

Chen 2018 Map

Updated 3D extinction map with improved coverage and resolution.

class Chen2018Query(EquirectangularDustMap):
    def __init__(self, map_fname=None):
        """Initialize Chen et al. 2018 map query."""

    def query(self, coords, **kwargs):
        """
        Query Chen 2018 3D extinction.

        Parameters:
        - coords (SkyCoord): Coordinates with distance

        Returns:
        - float | np.ndarray: Extinction values
        """

def fetch():
    """Download Chen 2018 map data."""

3D Map Usage Patterns

Distance-Resolved Extinction Profiles

from dustmaps.bayestar import BayestarQuery
from astropy.coordinates import SkyCoord
import astropy.units as u
import numpy as np
import matplotlib.pyplot as plt

# Initialize 3D map
bayestar = BayestarQuery()

# Create distance array
distances = np.logspace(1.5, 3.5, 50) * u.pc  # 30 pc to ~3000 pc

# Query extinction profile toward a specific direction
coords = SkyCoord(
    ra=270.0*u.deg,
    dec=0.0*u.deg,  # Galactic center direction
    distance=distances,
    frame='icrs'
)

extinctions = bayestar(coords)

# Plot extinction profile
plt.figure(figsize=(10, 6))
plt.semilogx(distances.value, extinctions, 'b-', linewidth=2)
plt.xlabel('Distance (pc)')
plt.ylabel('E(B-V)')
plt.title('Extinction Profile toward Galactic Center')
plt.grid(True, alpha=0.3)
plt.show()

Cumulative Extinction

# Calculate cumulative extinction to different distances
cumulative_ext = np.cumsum(np.diff(np.log(distances.value)) * extinctions[:-1])

plt.figure(figsize=(10, 6))
plt.semilogx(distances.value[:-1], cumulative_ext, 'r-', linewidth=2)
plt.xlabel('Distance (pc)')
plt.ylabel('Cumulative E(B-V)')
plt.title('Cumulative Extinction Profile')
plt.grid(True, alpha=0.3)
plt.show()

3D Map Comparison

from dustmaps.bayestar import BayestarQuery
from dustmaps.marshall import MarshallQuery

# Initialize multiple 3D maps
bayestar = BayestarQuery()
marshall = MarshallQuery()

# Compare at same location and distance
coord = SkyCoord(
    l=30.0*u.deg,
    b=5.0*u.deg,
    distance=1000*u.pc,
    frame='galactic'
)

bayestar_ext = bayestar(coord)
marshall_ext = marshall(coord)

print(f"Bayestar E(B-V): {bayestar_ext:.4f}")
print(f"Marshall A_Ks: {marshall_ext:.4f}")

Uncertainty Analysis

from dustmaps.marshall import MarshallQuery

marshall = MarshallQuery()

# Query with uncertainties
coord = SkyCoord(l=45.0*u.deg, b=0.0*u.deg, distance=500*u.pc, frame='galactic')
extinction, uncertainty = marshall(coord, return_sigma=True)

print(f"A_Ks: {extinction:.4f} ± {uncertainty:.4f}")

Install with Tessl CLI