0
# 3D Dust Maps
1

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

4
## Capabilities
5

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

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

10
```python { .api }
11
class BayestarQuery(DustMap):
12
    def __init__(self, map_fname=None, max_samples=None, version='bayestar2019'):
13
        """
14
        Initialize 3D Bayestar dust map query.
15

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

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

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

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

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

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

45
        Returns:
46
        - float | np.ndarray: Extinction values
47
        """
48

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

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

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

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

65
    Returns:
66
    - int | np.ndarray: HEALPix pixel indices
67
    """
68

69
def fetch(version='bayestar2019'):
70
    """
71
    Download Bayestar map data.
72

73
    Parameters:
74
    - version (str): Map version to download
75
    """
76
```
77

78
**Usage Example:**
79

80
```python
81
import dustmaps.bayestar
82
from dustmaps.bayestar import BayestarQuery
83
from astropy.coordinates import SkyCoord
84
import astropy.units as u
85

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

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

92
# Query with distance information
93
coord = SkyCoord(
94
    ra=180.0*u.deg,
95
    dec=30.0*u.deg,
96
    distance=500*u.pc,  # Distance is required for 3D maps
97
    frame='icrs'
98
)
99

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

103
# Query distance-resolved extinction profile
104
distances = np.linspace(100, 2000, 20) * u.pc
105
coords_3d = SkyCoord(
106
    ra=180.0*u.deg,
107
    dec=30.0*u.deg,
108
    distance=distances,
109
    frame='icrs'
110
)
111

112
extinction_profile = bayestar(coords_3d)
113
```
114

115
### Marshall Map (Marshall et al. 2006)
116

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

119
```python { .api }
120
class MarshallQuery(DustMap):
121
    def __init__(self, map_fname=None):
122
        """
123
        Initialize Marshall et al. 2006 3D map query.
124

125
        Parameters:
126
        - map_fname (str, optional): Path to Marshall map file
127
        """
128

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

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

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

142
def fetch(clobber=False):
143
    """
144
    Download Marshall map data.
145

146
    Parameters:
147
    - clobber (bool): Overwrite existing files
148
    """
149
```
150

151
### Leike & Enßlin 2019 Map
152

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

155
```python { .api }
156
class LeikeEnsslin2019Query(DustMap):
157
    def __init__(self, map_fname=None, **kwargs):
158
        """
159
        Initialize Leike & Enßlin 2019 3D map query.
160

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

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

169
        Parameters:
170
        - coords (SkyCoord): Coordinates with distance
171

172
        Returns:
173
        - float | np.ndarray: Dust density values
174
        """
175

176
def fetch():
177
    """Download Leike & Enßlin 2019 map data."""
178
```
179

180
### Leike 2020 Map
181

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

184
```python { .api }
185
class Leike2020Query(DustMap):
186
    def __init__(self, map_fname=None, **kwargs):
187
        """Initialize Leike et al. 2020 3D map query."""
188

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

193
        Parameters:
194
        - coords (SkyCoord): Coordinates with distance
195

196
        Returns:
197
        - float | np.ndarray: Dust density values
198
        """
199

200
def fetch():
201
    """Download Leike 2020 map data."""
202
```
203

204
### Edenhofer 2023 Map
205

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

208
```python { .api }
209
class Edenhofer2023Query(DustMap):
210
    def __init__(self, map_fname=None, **kwargs):
211
        """Initialize Edenhofer et al. 2023 3D map query."""
212

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

217
        Parameters:
218
        - coords (SkyCoord): Coordinates with distance
219

220
        Returns:
221
        - float | np.ndarray: Dust density values
222
        """
223

224
def fetch():
225
    """Download Edenhofer 2023 map data."""
226
```
227

228
### DECaPS Map (Zucker et al. 2025)
229

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

232
```python { .api }
233
class DECaPSQuery(DustMap):
234
    def __init__(self, map_fname=None, **kwargs):
235
        """Initialize DECaPS map query."""
236

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

241
        Parameters:
242
        - coords (SkyCoord): Coordinates with distance
243

244
        Returns:
245
        - float | np.ndarray: Extinction values
246
        """
247

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

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

255
def fetch():
256
    """Download DECaPS map data."""
257
```
258

259
### Chen 2014 Map
260

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

263
```python { .api }
264
class Chen2014Query(UnstructuredDustMap):
265
    def __init__(self, map_fname=None):
266
        """Initialize Chen et al. 2014 map query."""
267

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

272
        Parameters:
273
        - coords (SkyCoord): Coordinates with distance
274

275
        Returns:
276
        - float | np.ndarray: Extinction values
277
        """
278

279
def fetch():
280
    """Download Chen 2014 map data."""
281
```
282

283
### Chen 2018 Map
284

285
Updated 3D extinction map with improved coverage and resolution.
286

287
```python { .api }
288
class Chen2018Query(EquirectangularDustMap):
289
    def __init__(self, map_fname=None):
290
        """Initialize Chen et al. 2018 map query."""
291

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

296
        Parameters:
297
        - coords (SkyCoord): Coordinates with distance
298

299
        Returns:
300
        - float | np.ndarray: Extinction values
301
        """
302

303
def fetch():
304
    """Download Chen 2018 map data."""
305
```
306

307
## 3D Map Usage Patterns
308

309
### Distance-Resolved Extinction Profiles
310

311
```python
312
from dustmaps.bayestar import BayestarQuery
313
from astropy.coordinates import SkyCoord
314
import astropy.units as u
315
import numpy as np
316
import matplotlib.pyplot as plt
317

318
# Initialize 3D map
319
bayestar = BayestarQuery()
320

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

324
# Query extinction profile toward a specific direction
325
coords = SkyCoord(
326
    ra=270.0*u.deg,
327
    dec=0.0*u.deg,  # Galactic center direction
328
    distance=distances,
329
    frame='icrs'
330
)
331

332
extinctions = bayestar(coords)
333

334
# Plot extinction profile
335
plt.figure(figsize=(10, 6))
336
plt.semilogx(distances.value, extinctions, 'b-', linewidth=2)
337
plt.xlabel('Distance (pc)')
338
plt.ylabel('E(B-V)')
339
plt.title('Extinction Profile toward Galactic Center')
340
plt.grid(True, alpha=0.3)
341
plt.show()
342
```
343

344
### Cumulative Extinction
345

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

350
plt.figure(figsize=(10, 6))
351
plt.semilogx(distances.value[:-1], cumulative_ext, 'r-', linewidth=2)
352
plt.xlabel('Distance (pc)')
353
plt.ylabel('Cumulative E(B-V)')
354
plt.title('Cumulative Extinction Profile')
355
plt.grid(True, alpha=0.3)
356
plt.show()
357
```
358

359
### 3D Map Comparison
360

361
```python
362
from dustmaps.bayestar import BayestarQuery
363
from dustmaps.marshall import MarshallQuery
364

365
# Initialize multiple 3D maps
366
bayestar = BayestarQuery()
367
marshall = MarshallQuery()
368

369
# Compare at same location and distance
370
coord = SkyCoord(
371
    l=30.0*u.deg,
372
    b=5.0*u.deg,
373
    distance=1000*u.pc,
374
    frame='galactic'
375
)
376

377
bayestar_ext = bayestar(coord)
378
marshall_ext = marshall(coord)
379

380
print(f"Bayestar E(B-V): {bayestar_ext:.4f}")
381
print(f"Marshall A_Ks: {marshall_ext:.4f}")
382
```
383

384
### Uncertainty Analysis
385

386
```python
387
from dustmaps.marshall import MarshallQuery
388

389
marshall = MarshallQuery()
390

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

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