0
# Dataset Loading
1

2
Built-in access to GMT's extensive collection of global datasets including Earth relief, planetary data, geophysical grids, and sample datasets. All datasets are downloaded from GMT's data server and returned as xarray DataArrays with proper GMT metadata.
3

4
## Capabilities
5

6
### Earth Relief and Topography
7

8
Global digital elevation models at various resolutions.
9

10
```python { .api }
11
def load_earth_relief(resolution: str = "01d", region: Region | None = None, 
12
                      registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
13
    """
14
    Load global relief grid from ETOPO1, SRTM, or GMT global relief.
15
    
16
    Parameters:
17
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m", "30s", "15s", "03s", "01s")
18
    - region: Geographic extent [west, east, south, north] 
19
    - registration: Grid registration ("gridline" or "pixel")
20
    - use_srtm: Use SRTM data for high-resolution land areas
21
    
22
    Returns:
23
    xarray.DataArray: Global relief grid in meters
24
    """
25

26
def load_earth_age(resolution: str = "01d", region: Region | None = None, 
27
                   registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
28
    """
29
    Load a grid of seafloor crustal ages.
30
    
31
    Parameters:
32
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
33
    - region: Geographic extent
34
    - registration: Grid registration
35
    
36
    Returns:
37
    xarray.DataArray: Seafloor age grid in millions of years
38
    """
39

40
def load_earth_mask(resolution: str = "01d", region: Region | None = None,
41
                    registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
42
    """
43
    Load global mask grid distinguishing land and water areas.
44
    
45
    Parameters:
46
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m", "15s")
47
    - region: Geographic extent  
48
    - registration: Grid registration
49
    
50
    Returns:  
51
    xarray.DataArray: Mask grid (0=ocean, 1=land, 2=lake, 3=island_in_lake, 4=pond_in_island)
52
    """
53
```
54

55
### Earth Geophysical Data
56

57
Global grids of geophysical quantities.
58

59
```python { .api }
60
def load_earth_free_air_anomaly(resolution: str = "01d", region: Region | None = None,
61
                                registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
62
    """
63
    Load global free-air gravity anomaly grid.
64
    
65
    Parameters:
66
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
67
    - region: Geographic extent
68
    - registration: Grid registration
69
    
70
    Returns:
71
    xarray.DataArray: Free-air gravity anomaly in mGal
72
    """
73

74
def load_earth_magnetic_anomaly(resolution: str = "01d", region: Region | None = None,
75
                                registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
76
    """
77
    Load global magnetic anomaly grid.
78
    
79
    Parameters:
80
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
81
    - region: Geographic extent
82
    - registration: Grid registration
83
    
84
    Returns:
85
    xarray.DataArray: Magnetic anomaly in nT
86
    """
87

88
def load_earth_geoid(resolution: str = "01d", region: Region | None = None,
89
                     registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
90
    """
91
    Load global geoid grids.
92
    
93
    Parameters:
94
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
95
    - region: Geographic extent
96
    - registration: Grid registration
97
    
98
    Returns:
99
    xarray.DataArray: Geoid height in meters
100
    """
101

102
def load_earth_vertical_gravity_gradient(resolution: str = "01d", region: Region | None = None,
103
                                         registration: GridRegistration | None = None, 
104
                                         **kwargs) -> xr.DataArray:
105
    """
106
    Load global vertical gravity gradient grid.
107
    
108
    Parameters:
109
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
110
    - region: Geographic extent  
111
    - registration: Grid registration
112
    
113
    Returns:
114
    xarray.DataArray: Vertical gravity gradient in Eotvos units
115
    """
116

117
def load_earth_deflection(resolution: str = "01d", region: Region | None = None,
118
                          registration: GridRegistration | None = None, 
119
                          component: Literal["east", "north"] = "east", **kwargs) -> xr.DataArray:
120
    """
121
    Load vertical deflection grids.
122
    
123
    Parameters:
124
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
125
    - region: Geographic extent
126
    - registration: Grid registration  
127
    - component: Deflection component ("east" or "north")
128
    
129
    Returns:
130
    xarray.DataArray: Vertical deflection in arc-seconds
131
    """
132

133
def load_earth_dist(resolution: str = "01d", region: Region | None = None,
134
                    registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
135
    """
136
    Load distance to nearest point on land.
137
    
138
    Parameters:
139
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
140
    - region: Geographic extent
141
    - registration: Grid registration
142
    
143
    Returns:
144
    xarray.DataArray: Distance to land in kilometers
145
    """
146
```
147

148
### Earth Ocean Data
149

150
Ocean-specific global datasets.
151

152
```python { .api }
153
def load_earth_mean_sea_surface(resolution: str = "01d", region: Region | None = None,
154
                                registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
155
    """
156
    Load global mean sea surface grid.
157
    
158
    Parameters:
159
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
160
    - region: Geographic extent
161
    - registration: Grid registration
162
    
163
    Returns:
164
    xarray.DataArray: Mean sea surface height in meters
165
    """
166

167
def load_earth_mean_dynamic_topography(resolution: str = "01d", region: Region | None = None,
168
                                       registration: GridRegistration | None = None, 
169
                                       **kwargs) -> xr.DataArray:
170
    """
171
    Load global mean dynamic topography grid.
172
    
173
    Parameters:
174
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
175
    - region: Geographic extent
176
    - registration: Grid registration
177
    
178
    Returns:
179
    xarray.DataArray: Mean dynamic topography in meters
180
    """
181
```
182

183
### Earth Satellite Imagery
184

185
Global satellite imagery datasets.
186

187
```python { .api }
188
def load_blue_marble(resolution: str = "01d", region: Region | None = None,
189
                     registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
190
    """
191
    Load a blue marble Earth day image.
192
    
193
    Parameters:
194
    - resolution: Image resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
195
    - region: Geographic extent
196
    - registration: Grid registration
197
    
198
    Returns:
199
    xarray.DataArray: RGB satellite image
200
    """
201

202
def load_black_marble(resolution: str = "01d", region: Region | None = None,
203
                      registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
204
    """
205
    Load a black marble Earth night image.
206
    
207
    Parameters:
208
    - resolution: Image resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
209
    - region: Geographic extent
210
    - registration: Grid registration
211
    
212
    Returns:
213
    xarray.DataArray: RGB nighttime satellite image
214
    """
215
```
216

217
### Planetary Relief Data
218

219
Digital elevation models for other planets and moons.
220

221
```python { .api }
222
def load_mars_relief(resolution: str = "01d", region: Region | None = None,
223
                     registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
224
    """
225
    Load global relief grid for Mars.
226
    
227
    Parameters:
228
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
229
    - region: Geographic extent  
230
    - registration: Grid registration
231
    
232
    Returns:
233
    xarray.DataArray: Mars elevation grid in meters
234
    """
235

236
def load_moon_relief(resolution: str = "01d", region: Region | None = None,
237
                     registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
238
    """
239
    Load global relief grid for the Moon.
240
    
241
    Parameters:
242
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
243
    - region: Geographic extent
244
    - registration: Grid registration
245
    
246
    Returns:
247
    xarray.DataArray: Lunar elevation grid in meters
248
    """
249

250
def load_mercury_relief(resolution: str = "01d", region: Region | None = None,
251
                        registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
252
    """
253
    Load global relief grid for Mercury.
254
    
255
    Parameters:
256
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
257
    - region: Geographic extent
258
    - registration: Grid registration
259
    
260
    Returns:
261
    xarray.DataArray: Mercury elevation grid in meters
262
    """
263

264
def load_venus_relief(resolution: str = "01d", region: Region | None = None,
265
                      registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
266
    """
267
    Load global relief grid for Venus.
268
    
269
    Parameters:
270
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
271
    - region: Geographic extent
272
    - registration: Grid registration
273
    
274
    Returns:
275
    xarray.DataArray: Venus elevation grid in meters
276
    """
277

278
def load_pluto_relief(resolution: str = "01d", region: Region | None = None,
279
                      registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
280
    """
281
    Load global relief grid for Pluto.
282
    
283
    Parameters:
284
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
285
    - region: Geographic extent
286
    - registration: Grid registration
287
    
288
    Returns:
289
    xarray.DataArray: Pluto elevation grid in meters
290
    """
291
```
292

293
### Sample and Test Data
294

295
Built-in sample datasets for testing and examples.
296

297
```python { .api }
298
def list_sample_data() -> list:
299
    """
300
    Get list of names of all available sample datasets.
301
    
302
    Returns:
303
    list: Names of available sample datasets
304
    """
305

306
def load_sample_data(name: str) -> xr.DataArray | pd.DataFrame:
307
    """
308
    Load sample data included with GMT.
309
    
310
    Parameters:
311
    - name: Name of sample dataset
312
    
313
    Returns:
314
    xarray.DataArray or pandas.DataFrame: Sample data
315
    
316
    Available datasets include:
317
    - "@earth_relief_01d_g": 1 degree global relief
318
    - "@earth_age_01m_g": 1 arc-minute seafloor age
319
    - "@hotspots.txt": Global hotspot locations
320
    - "@ridge.txt": Mid-ocean ridge locations
321
    - "@fractures.txt": Fracture zone locations
322
    - "@seamounts.txt": Seamount locations
323
    """
324
```
325

326
### Web Map Tiles
327

328
Access to web-based map tile services.
329

330
```python { .api }
331
def load_tile_map(region: Region, zoom: int = "auto", source: str = "OpenStreetMap",
332
                  lonlat: bool = True, wait: int = 0, max_retries: int = 2, **kwargs) -> xr.DataArray:
333
    """
334
    Load tile maps from various web map servers.
335
    
336
    Parameters:
337
    - region: Geographic extent [west, east, south, north]
338
    - zoom: Zoom level (1-19, or "auto" for automatic selection)
339
    - source: Tile source ("OpenStreetMap", "OpenTopoMap", "ESRI_World_Imagery", etc.)
340
    - lonlat: Input region in longitude/latitude (True) or tile coordinates (False)
341
    - wait: Wait time between tile requests in seconds
342
    - max_retries: Maximum number of retry attempts
343
    
344
    Returns:
345
    xarray.DataArray: RGB tile map image
346
    
347
    Available sources:
348
    - "OpenStreetMap": Standard OpenStreetMap tiles
349
    - "OpenTopoMap": Topographic map tiles  
350
    - "ESRI_World_Imagery": ESRI satellite imagery
351
    - "ESRI_World_Terrain_Base": ESRI terrain base map
352
    - "Google_Satellite": Google satellite imagery (requires API key)
353
    - "Google_Terrain": Google terrain maps (requires API key)
354
    """
355
```
356

357
## Usage Examples
358

359
### Basic Dataset Loading
360

361
```python
362
import pygmt
363

364
# Load global relief at 1 degree resolution
365
relief = pygmt.datasets.load_earth_relief(resolution="01d")
366
print(f"Grid shape: {relief.shape}")
367
print(f"Data range: {relief.min().values:.1f} to {relief.max().values:.1f} meters")
368

369
# Load regional high-resolution relief
370
regional_relief = pygmt.datasets.load_earth_relief(
371
    resolution="03s",
372
    region=[120, 125, 20, 25]  # Taiwan region
373
)
374
print(f"Regional grid shape: {regional_relief.shape}")
375
```
376

377
### Geophysical Data Analysis
378

379
```python
380
import pygmt
381
import matplotlib.pyplot as plt
382

383
# Load magnetic anomaly data
384
mag_data = pygmt.datasets.load_earth_magnetic_anomaly(
385
    resolution="02m", 
386
    region=[-20, 20, -20, 20]  # Atlantic mid-ocean ridge region
387
)
388

389
# Load gravity data for comparison
390
gravity_data = pygmt.datasets.load_earth_free_air_anomaly(
391
    resolution="02m",
392
    region=[-20, 20, -20, 20]
393
)
394

395
# Plot both datasets
396
fig = pygmt.Figure()
397

398
# Plot magnetic anomalies
399
fig.subplot(nrows=1, ncols=2, figsize="20c", frame="WSen")
400
fig.set_panel(panel=0)
401
fig.grdimage(grid=mag_data, cmap="polar", projection="M8c")
402
fig.coast(shorelines=True)
403
fig.colorbar(frame='a500+l"Magnetic anomaly (nT)"')
404

405
# Plot gravity anomalies  
406
fig.set_panel(panel=1)
407
fig.grdimage(grid=gravity_data, cmap="polar", projection="M8c")
408
fig.coast(shorelines=True)
409
fig.colorbar(frame='a50+l"Gravity anomaly (mGal)"')
410

411
fig.show()
412
```
413

414
### Planetary Data Visualization
415

416
```python
417
import pygmt
418

419
# Load Mars elevation data
420
mars_relief = pygmt.datasets.load_mars_relief(resolution="06m")
421

422
# Create a global Mars map
423
fig = pygmt.Figure()
424
fig.grdimage(
425
    grid=mars_relief,
426
    projection="W15c",
427
    cmap="geo",
428
    frame="a60f30"
429
)
430
fig.colorbar(frame='a5000+l"Elevation (m)"')
431
fig.show()
432

433
# Compare with Earth
434
earth_relief = pygmt.datasets.load_earth_relief(resolution="06m")
435

436
fig = pygmt.Figure()
437
fig.subplot(nrows=2, ncols=1, figsize="15c/20c")
438

439
# Earth
440
fig.set_panel(panel=0)
441
fig.grdimage(grid=earth_relief, projection="W?", cmap="geo")
442
fig.colorbar(frame='a5000+l"Earth elevation (m)"')
443

444
# Mars  
445
fig.set_panel(panel=1)
446
fig.grdimage(grid=mars_relief, projection="W?", cmap="geo")
447
fig.colorbar(frame='a5000+l"Mars elevation (m)"')
448

449
fig.show()
450
```
451

452
### Sample Data Exploration
453

454
```python
455
import pygmt
456

457
# List available sample datasets
458
datasets = pygmt.datasets.list_sample_data()
459
print("Available sample datasets:")
460
for dataset in datasets[:10]:  # Show first 10
461
    print(f"  {dataset}")
462

463
# Load hotspot locations
464
hotspots = pygmt.datasets.load_sample_data("@hotspots.txt")
465
print(f"\nHotspots data shape: {hotspots.shape}")
466
print(f"Columns: {hotspots.columns.tolist()}")
467

468
# Plot hotspots on a global map
469
fig = pygmt.Figure()
470
fig.basemap(region="global", projection="W15c", frame="a60f30")
471
fig.coast(land="lightgray", water="lightblue")
472
fig.plot(
473
    data=hotspots,
474
    style="c0.2c",
475
    fill="red",
476
    pen="0.5p,black"
477
)
478
fig.show()
479
```
480

481
### Web Tile Integration
482

483
```python
484
import pygmt
485

486
# Load OpenStreetMap tiles for a city
487
osm_tiles = pygmt.datasets.load_tile_map(
488
    region=[-74.02, -73.97, 40.75, 40.78],  # Manhattan, NYC
489
    zoom=12,
490
    source="OpenStreetMap"
491
)
492

493
# Create map with tiles as background
494
fig = pygmt.Figure()
495
fig.grdimage(
496
    grid=osm_tiles,
497
    projection="M15c",
498
    frame="a0.01f0.005"
499
)
500

501
# Add some sample points
502
sample_points = [
503
    [-73.985, 40.758],  # Times Square
504
    [-73.971, 40.764],  # Central Park
505
    [-73.997, 40.731]   # World Trade Center
506
]
507

508
for point in sample_points:
509
    fig.plot(x=point[0], y=point[1], style="c0.3c", fill="yellow", pen="1p,black")
510

511
fig.show()
512
```
513

514
### Multi-Resolution Analysis
515

516
```python
517
import pygmt
518

519
# Load same region at different resolutions
520
region = [120, 140, 20, 40]  # East Asia
521

522
resolutions = ["01d", "30m", "15m", "05m"]
523
grids = {}
524

525
for res in resolutions:
526
    print(f"Loading {res} resolution data...")
527
    grids[res] = pygmt.datasets.load_earth_relief(
528
        resolution=res,
529
        region=region
530
    )
531
    print(f"  Grid shape: {grids[res].shape}")
532
    print(f"  Grid spacing: {grids[res].gmt.spacing}")
533

534
# Plot comparison
535
fig = pygmt.Figure()
536
fig.subplot(nrows=2, ncols=2, figsize="20c", frame="WSen")
537

538
for i, res in enumerate(resolutions):
539
    fig.set_panel(panel=i)
540
    fig.grdimage(grid=grids[res], projection="M?", cmap="geo")
541
    fig.coast(shorelines=True)
542
    fig.text(text=f"Resolution: {res}", position="TL", font="12p,Helvetica-Bold")
543

544
fig.show()
545
```
546

547
## Dataset Resolution Guide
548

549
### Available Resolutions
550

551
All Earth datasets support these resolutions:
552
- **01d**: 1 degree (~111 km at equator)
553
- **30m**: 30 arc-minutes (~55 km)  
554
- **20m**: 20 arc-minutes (~37 km)
555
- **15m**: 15 arc-minutes (~28 km)
556
- **10m**: 10 arc-minutes (~18 km)
557
- **06m**: 6 arc-minutes (~11 km)
558
- **05m**: 5 arc-minutes (~9 km)
559
- **04m**: 4 arc-minutes (~7 km)
560
- **03m**: 3 arc-minutes (~5.5 km)
561
- **02m**: 2 arc-minutes (~3.7 km)
562
- **01m**: 1 arc-minute (~1.8 km)
563
- **30s**: 30 arc-seconds (~900 m)
564
- **15s**: 15 arc-seconds (~450 m)
565
- **03s**: 3 arc-seconds (~90 m)
566
- **01s**: 1 arc-second (~30 m)
567

568
### Memory and Performance Considerations
569

570
Higher resolution datasets require more memory and processing time:
571
- **Global 01d**: ~0.5 MB, instant download
572
- **Global 15m**: ~25 MB, fast download
573
- **Global 01m**: ~1.5 GB, slower download  
574
- **Regional 15s**: Can be very large for big regions
575

576
Use appropriate resolution for your analysis needs and computational resources.