0
# dustmaps
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: dustmaps
7
- **Language**: Python
8
- **Installation**: `pip install dustmaps`
9

10
## Core Imports
11

12
Configuration management:
13

14
```python
15
from dustmaps.config import config
16
```
17

18
Specific dust maps (examples):
19

20
```python
21
from dustmaps.sfd import SFDQuery
22
from dustmaps.bayestar import BayestarQuery
23
from dustmaps.planck import PlanckQuery
24
```
25

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

28
## Basic Usage
29

30
```python
31
from dustmaps.sfd import SFDQuery
32
from astropy.coordinates import SkyCoord
33

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

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

42
# Initialize SFD dust map query
43
sfd = SFDQuery()
44

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

50
# Query multiple coordinates
51
coords = SkyCoord(
52
    ra=[75.0, 130.0, 200.0],
53
    dec=[10.0, -20.0, 45.0],
54
    unit='deg',
55
    frame='icrs'
56
)
57
extinctions = sfd(coords)
58
print(f"E(B-V) values: {extinctions}")
59

60
# Query using Galactic coordinates
61
gal_coord = SkyCoord(l=180.0, b=30.0, unit='deg', frame='galactic')
62
extinction_gal = sfd(gal_coord)
63
```
64

65
## Architecture
66

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

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

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

77
## Capabilities
78

79
### 2D Dust Maps
80

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

83
```python { .api }
84
class SFDQuery(DustMap):
85
    def __init__(self, map_dir=None): ...
86
    def query(self, coords, order=1): ...
87

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

92
class CSFDQuery(DustMap):
93
    def __init__(self, map_dir=None): ...
94
    def query(self, coords, **kwargs): ...
95
```
96

97
[2D Dust Maps](./2d-maps.md)
98

99
### 3D Dust Maps
100

101
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.
102

103
```python { .api }
104
class BayestarQuery(DustMap):
105
    def __init__(self, map_fname=None, max_samples=None, version='bayestar2019'): ...
106
    def query(self, coords, mode='random_sample', return_flags=False, pct=None): ...
107

108
class MarshallQuery(DustMap):
109
    def __init__(self, map_fname=None): ...
110
    def query(self, coords, return_sigma=False): ...
111
```
112

113
[3D Dust Maps](./3d-maps.md)
114

115
### Configuration and Data Management
116

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

119
```python { .api }
120
class Configuration:
121
    def __init__(self, fname): ...
122
    def __getitem__(self, key): ...
123
    def __setitem__(self, key, value): ...
124
    def get(self, key, default=None): ...
125

126
def fetch(): ...  # Available in each map module
127
```
128

129
[Configuration](./config.md)
130

131
### Base Classes and Utilities
132

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

135
```python { .api }
136
class DustMap:
137
    def query(self, coords, **kwargs): ...
138
    def query_gal(self, l, b, d=None, **kwargs): ...
139
    def query_equ(self, ra, dec, d=None, frame='icrs', **kwargs): ...
140

141
class WebDustMap:
142
    def query(self, coords, **kwargs): ...
143
```
144

145
[Base Classes](./base-classes.md)
146

147
## Types
148

149
```python { .api }
150
from astropy.coordinates import SkyCoord
151
from astropy.units import Quantity
152
import numpy as np
153

154
# Core coordinate type
155
SkyCoord: # astropy.coordinates.SkyCoord objects
156

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

161
# Configuration types
162
ConfigDict: dict[str, str | float | bool]  # Configuration options
163
FilePath: str  # File system paths
164
```