or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

2d-maps.md3d-maps.mdbase-classes.mdconfig.mdindex.md
tile.json

tessl/pypi-dustmaps

Uniform interface for multiple dust reddening maps

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/dustmaps@1.0.x

To install, run

npx @tessl/cli install tessl/pypi-dustmaps@1.0.0

index.mddocs/

dustmaps

A comprehensive Python library for accessing and working with 2D and 3D maps of interstellar dust reddening and extinction across the sky. dustmaps provides a uniform interface for querying multiple dust map datasets from various astronomical surveys and studies, standardizing access to over 15 different dust maps with automatic coordinate transformations and units.

Package Information

  • Package Name: dustmaps
  • Language: Python
  • Installation: pip install dustmaps

Core Imports

Configuration management:

from dustmaps.config import config

Specific dust maps (examples):

from dustmaps.sfd import SFDQuery
from dustmaps.bayestar import BayestarQuery
from dustmaps.planck import PlanckQuery

Note: The main dustmaps package has no public exports in __init__.py. Always import from specific submodules.

Basic Usage

from dustmaps.sfd import SFDQuery
from astropy.coordinates import SkyCoord

# Configure data directory (first-time setup)
from dustmaps.config import config
config['data_dir'] = '/path/to/data/directory'

# Download SFD map data (first-time setup)
import dustmaps.sfd
dustmaps.sfd.fetch()

# Initialize SFD dust map query
sfd = SFDQuery()

# Query single coordinate
coord = SkyCoord(ra=75.0, dec=10.0, unit='deg', frame='icrs')
extinction = sfd(coord)
print(f"E(B-V): {extinction:.4f}")

# Query multiple coordinates
coords = SkyCoord(
    ra=[75.0, 130.0, 200.0],
    dec=[10.0, -20.0, 45.0],
    unit='deg',
    frame='icrs'
)
extinctions = sfd(coords)
print(f"E(B-V) values: {extinctions}")

# Query using Galactic coordinates
gal_coord = SkyCoord(l=180.0, b=30.0, unit='deg', frame='galactic')
extinction_gal = sfd(gal_coord)

Architecture

dustmaps implements a modular architecture centered around standardized dust map queries:

  • Base Classes: Abstract DustMap and WebDustMap classes define common query interfaces
  • Map Implementations: Individual modules for each dust map dataset (SFD, Bayestar, Planck, etc.)
  • Coordinate System: Full astropy.coordinates integration with automatic frame conversions
  • Data Management: Centralized configuration system and standardized data fetching
  • Query Types: Support for both 2D (line-of-sight) and 3D (distance-resolved) extinction maps

This design provides a consistent API across all dust maps while allowing specialized functionality for different map types and coordinate systems.

Capabilities

2D Dust Maps

Line-of-sight integrated extinction maps that provide total dust column density measurements. These maps cover the full sky with varying resolution and accuracy.

class SFDQuery(DustMap):
    def __init__(self, map_dir=None): ...
    def query(self, coords, order=1): ...

class PlanckQuery(DustMap):
    def __init__(self, map_fname=None, component='extragalactic'): ...
    def query(self, coords, **kwargs): ...

class CSFDQuery(DustMap):
    def __init__(self, map_dir=None): ...
    def query(self, coords, **kwargs): ...

2D Dust Maps

3D Dust Maps

Distance-resolved extinction maps providing dust density as a function of distance along lines of sight. These maps enable 3D extinction corrections and dust distribution studies.

class BayestarQuery(DustMap):
    def __init__(self, map_fname=None, max_samples=None, version='bayestar2019'): ...
    def query(self, coords, mode='random_sample', return_flags=False, pct=None): ...

class MarshallQuery(DustMap):
    def __init__(self, map_fname=None): ...
    def query(self, coords, return_sigma=False): ...

3D Dust Maps

Configuration and Data Management

System for managing dust map data storage, downloading map files, and configuring package behavior.

class Configuration:
    def __init__(self, fname): ...
    def __getitem__(self, key): ...
    def __setitem__(self, key, value): ...
    def get(self, key, default=None): ...

def fetch(): ...  # Available in each map module

Configuration

Base Classes and Utilities

Foundation classes and utility functions for coordinate transformations, data loading, and map querying.

class DustMap:
    def query(self, coords, **kwargs): ...
    def query_gal(self, l, b, d=None, **kwargs): ...
    def query_equ(self, ra, dec, d=None, frame='icrs', **kwargs): ...

class WebDustMap:
    def query(self, coords, **kwargs): ...

Base Classes

Types

from astropy.coordinates import SkyCoord
from astropy.units import Quantity
import numpy as np

# Core coordinate type
SkyCoord: # astropy.coordinates.SkyCoord objects

# Return types
ExtinctionValue: float | np.ndarray  # E(B-V) extinction values
ExtinctionWithUncertainty: tuple[float | np.ndarray, float | np.ndarray]  # (value, sigma)

# Configuration types
ConfigDict: dict[str, str | float | bool]  # Configuration options
FilePath: str  # File system paths