0
# Data Processing
1

2
Grid and table data processing functions that wrap GMT's powerful analysis capabilities. These functions provide gridding, filtering, sampling, mathematical operations, and coordinate transformations for geospatial data.
3

4
## Capabilities
5

6
### Gridding Functions
7

8
Convert irregular (x, y, z) data into regular grids using various interpolation methods.
9

10
```python { .api }
11
def surface(data: PathLike | TableLike | None = None, **kwargs):
12
    """
13
    Grid table data using adjustable tension continuous curvature splines.
14
    
15
    Parameters:
16
    - data: Input data file or table with x, y, z columns
17
    - region: Output grid extent [west, east, south, north]
18
    - spacing: Grid spacing (dx, dy)
19
    - tension: Tension parameter (0-1, default 0)
20
    - convergence: Convergence criteria
21
    - max_iterations: Maximum iterations
22
    - mask: Apply land/ocean mask
23
    - clipgrid: Clip output to input data bounds
24
    
25
    Returns:
26
    xarray.DataArray: Output grid
27
    """
28

29
def nearneighbor(data: PathLike | TableLike | None = None, **kwargs):
30
    """
31
    Grid table data using a "Nearest neighbor" algorithm.
32
    
33
    Parameters:
34
    - data: Input data file or table
35
    - region: Output grid extent  
36
    - spacing: Grid spacing
37
    - search_radius: Search radius for neighbors
38
    - sectors: Number of sectors for searching
39
    - min_sectors: Minimum sectors that must have data
40
    - empty: Value to assign to empty nodes
41
    
42
    Returns:
43
    xarray.DataArray: Output grid
44
    """
45

46
def triangulate(data: PathLike | TableLike | None = None, **kwargs):
47
    """
48
    Do optimal (Delaunay) triangulation and gridding of Cartesian table data.
49
    
50
    Parameters:
51
    - data: Input data file or table
52
    - region: Output grid extent
53
    - spacing: Grid spacing for optional gridding
54
    - derivatives: Output derivative grids
55
    - unity: Normalize output by triangle areas
56
    - edges: Output triangle edges
57
    
58
    Returns:
59
    xarray.DataArray or None: Output grid (if gridding requested)
60
    """
61

62
def xyz2grd(data: PathLike | TableLike | None = None, **kwargs):
63
    """
64
    Convert data table to a grid.
65
    
66
    Parameters:
67
    - data: Input xyz data file or table
68
    - region: Grid extent
69
    - spacing: Grid spacing
70
    - registration: Grid registration (gridline/pixel)
71
    - duplicate: How to handle duplicate coordinates (mean/median/mode/lower/upper)
72
    - statistics: Report statistics about input data
73
    
74
    Returns:
75
    xarray.DataArray: Output grid
76
    """
77

78
def sph2grd(data: PathLike | TableLike | None = None, **kwargs):
79
    """
80
    Compute grid from spherical harmonic coefficients.
81
    
82
    Parameters:
83
    - data: Spherical harmonic coefficients file or table
84
    - region: Output grid extent
85
    - spacing: Grid spacing
86
    - normalize: Normalization method
87
    - format: Input coefficient format
88
    
89
    Returns:
90
    xarray.DataArray: Output grid
91
    """
92

93
def sphdistance(data: PathLike | TableLike | None = None, **kwargs):
94
    """
95
    Create Voronoi distance, node, or natural nearest-neighbor grid.
96
    
97
    Parameters:
98
    - data: Input point data
99
    - region: Output grid extent
100
    - spacing: Grid spacing
101
    - quantity: Output quantity (distance/node_id/natural_weights)
102
    - unit: Distance unit
103
    
104
    Returns:
105
    xarray.DataArray: Output grid
106
    """
107

108
def sphinterpolate(data: PathLike | TableLike | None = None, **kwargs):
109
    """
110
    Spherical gridding in tension of data on a sphere.
111
    
112
    Parameters:
113
    - data: Input data on sphere
114
    - region: Output grid extent
115
    - spacing: Grid spacing
116
    - tension: Tension parameter
117
    - iterations: Number of iterations
118
    
119
    Returns:
120
    xarray.DataArray: Output grid
121
    """
122
```
123

124
### Grid Processing Functions
125

126
Modify, filter, and analyze existing grids.
127

128
```python { .api }
129
def grdfilter(grid: PathLike | xr.DataArray, **kwargs):
130
    """
131
    Filter a grid in the space/time domain.
132
    
133
    Parameters:
134
    - grid: Input grid file or xarray DataArray
135
    - filter: Filter type and parameters (boxcar/cosine/gaussian/median/mode)
136
    - distance: Filter full width
137
    - nans: How to handle NaN values
138
    - toggle: Toggle between high-pass and low-pass filtering
139
    
140
    Returns:
141
    xarray.DataArray: Filtered grid
142
    """
143

144
def grdgradient(grid: PathLike | xr.DataArray, **kwargs):
145
    """
146
    Compute directional gradients from a grid.
147
    
148
    Parameters:
149
    - grid: Input grid file or xarray DataArray
150
    - azimuth: Azimuth for directional derivative (degrees)
151
    - slope_file: Output slope magnitude grid
152
    - aspect_file: Output aspect (direction) grid  
153
    - normalize: Normalize gradients
154
    - sigma: Smoothing sigma for gradient calculation
155
    
156
    Returns:
157
    xarray.DataArray: Gradient grid
158
    """
159

160
def grdsample(grid: PathLike | xr.DataArray, **kwargs):
161
    """
162
    Resample a grid onto a new lattice.
163
    
164
    Parameters:
165
    - grid: Input grid file or xarray DataArray
166
    - region: Output grid extent
167
    - spacing: Output grid spacing
168
    - registration: Output grid registration
169
    - translate: Translate grid by offset
170
    - interpolation: Interpolation method (bilinear/bicubic/nearest)
171
    
172
    Returns:
173
    xarray.DataArray: Resampled grid
174
    """
175

176
def grdcut(grid: PathLike | xr.DataArray, **kwargs):
177
    """
178
    Extract subsets from a grid.
179
    
180
    Parameters:
181
    - grid: Input grid file or xarray DataArray
182
    - region: Subset extent [west, east, south, north]
183
    - extend: Extend region if needed
184
    - nans: Replace nodes outside region with NaN
185
    
186
    Returns:
187
    xarray.DataArray: Subset grid
188
    """
189

190
def grdclip(grid: PathLike | xr.DataArray, **kwargs):
191
    """
192
    Clip the range of grid values.
193
    
194
    Parameters:
195
    - grid: Input grid file or xarray DataArray
196
    - above: Clip values above this level
197
    - below: Clip values below this level
198
    - between: Clip values between two levels
199
    - new_high: New value for clipped high values
200
    - new_low: New value for clipped low values
201
    
202
    Returns:
203
    xarray.DataArray: Clipped grid
204
    """
205

206
def grdfill(grid: PathLike | xr.DataArray, **kwargs):
207
    """
208
    Interpolate across holes in a grid.
209
    
210
    Parameters:
211
    - grid: Input grid with holes (NaN values)
212
    - algorithm: Interpolation algorithm (constant/nearest/akima/spline)
213
    - radius: Search radius for hole filling
214
    - mode: Fill mode (all/edge/interior)
215
    
216
    Returns:
217
    xarray.DataArray: Filled grid
218
    """
219

220
def grdhisteq(grid: PathLike | xr.DataArray, **kwargs):
221
    """
222
    Perform histogram equalization for a grid.
223
    
224
    Parameters:
225
    - grid: Input grid file or xarray DataArray
226
    - divisions: Number of divisions for histogram equalization
227
    - output_type: Output data type
228
    - quadratic: Use quadratic intensity transformation
229
    
230
    Returns:
231
    xarray.DataArray: Histogram-equalized grid
232
    """
233

234
def grdlandmask(**kwargs):
235
    """
236
    Create a "wet/dry" mask grid from shoreline data.
237
    
238
    Parameters:
239
    - region: Grid extent
240
    - spacing: Grid spacing
241
    - registration: Grid registration
242
    - resolution: Shoreline resolution (full/high/intermediate/low/crude)
243
    - area_thresh: Minimum feature area
244
    - mask_type: Mask values (0/1 or 1/0 for land/water)
245
    
246
    Returns:
247
    xarray.DataArray: Land/water mask grid
248
    """
249

250
def grdproject(grid: PathLike | xr.DataArray, **kwargs):
251
    """
252
    Forward and inverse map transformation of grids.
253
    
254
    Parameters:
255
    - grid: Input grid file or xarray DataArray
256
    - projection: Target projection
257
    - region: Output region (if different from input)
258
    - spacing: Output spacing
259
    - interpolation: Resampling method
260
    - inverse: Perform inverse projection
261
    - center: Center coordinates for projection
262
    
263
    Returns:
264
    xarray.DataArray: Projected grid
265
    """
266

267
def grdvolume(grid: PathLike | xr.DataArray, **kwargs):
268
    """
269
    Calculate grid volume and area constrained by a contour.
270
    
271
    Parameters:
272
    - grid: Input grid file or xarray DataArray
273
    - contour: Contour value for volume calculation
274
    - unit: Area unit (squared map unit)
275
    - find_volume: Calculate volume above/below contour
276
    
277
    Returns:
278
    dict: Volume and area statistics
279
    """
280
```
281

282
### Grid Information and Conversion
283

284
Extract information from grids and convert between formats.
285

286
```python { .api }
287
def grdinfo(grid: PathLike | xr.DataArray, **kwargs):
288
    """
289
    Extract information from grids.
290
    
291
    Parameters:
292
    - grid: Input grid file or xarray DataArray
293
    - verbose: Verbose output with full statistics
294
    - force_scan: Force reading entire grid for statistics
295
    - per_column: Report statistics per column
296
    - nearest_multiple: Round spacing to nearest multiple
297
    
298
    Returns:
299
    str: Grid information string
300
    """
301

302
def grd2xyz(grid: PathLike | xr.DataArray, **kwargs):
303
    """
304
    Convert grid to data table.
305
    
306
    Parameters:
307
    - grid: Input grid file or xarray DataArray
308
    - region: Subset region for conversion
309
    - output_type: Output format (xyz/table)
310
    - reverse: List z-values in reverse order
311
    - weights: Output (x,y,z,w) where w is weight
312
    
313
    Returns:
314
    pandas.DataFrame: Output data table
315
    """
316

317
def grd2cpt(**kwargs):
318
    """
319
    Make a color palette table from grid(s).
320
    
321
    Parameters:
322
    - grid: Input grid file(s) or xarray DataArray(s)
323
    - cmap: Master color palette to use as base
324
    - reverse: Reverse the color progression
325
    - symmetric: Make color palette symmetric about zero
326
    - series: Set specific z-value range
327
    - levels: Number of levels in output CPT
328
    
329
    Returns:
330
    str: Color palette table data
331
    """
332
```
333

334
### Table Data Processing
335

336
Process and analyze tabular (x, y, z) data.
337

338
```python { .api }
339
def blockmean(data: PathLike | TableLike | None = None, **kwargs):
340
    """
341
    Block average (x,y,z) data tables by mean estimation.
342
    
343
    Parameters:
344
    - data: Input data file or table
345
    - region: Processing region
346
    - spacing: Block size (dx, dy)
347
    - registration: Block registration (gridline/pixel)
348
    - summary: Summary mode for multiple values per block
349
    - weights: Use weighted mean
350
    - extend: Extend blocks to region boundary
351
    
352
    Returns:
353
    pandas.DataFrame: Block-averaged data
354
    """
355

356
def blockmedian(data: PathLike | TableLike | None = None, **kwargs):
357
    """
358
    Block average (x,y,z) data tables by median estimation.
359
    
360
    Parameters:
361
    - data: Input data file or table  
362
    - region: Processing region
363
    - spacing: Block size
364
    - registration: Block registration
365
    - quantile: Use L1 (median) or other quantile
366
    - summary: Summary mode for blocks
367
    
368
    Returns:
369
    pandas.DataFrame: Block-processed data
370
    """
371

372
def blockmode(data: PathLike | TableLike | None = None, **kwargs):
373
    """
374
    Block average (x,y,z) data tables by mode estimation.
375
    
376
    Parameters:
377
    - data: Input data file or table
378
    - region: Processing region
379
    - spacing: Block size
380
    - registration: Block registration
381
    - width: Half-width for mode search
382
    - summary: Summary mode for blocks
383
    
384
    Returns:  
385
    pandas.DataFrame: Block-processed data
386
    """
387

388
def binstats(data: PathLike | TableLike | None = None, **kwargs):
389
    """
390
    Bin spatial data and calculate statistics per bin.
391
    
392
    Parameters:
393
    - data: Input data file or table
394
    - region: Processing region
395
    - spacing: Bin size  
396
    - statistic: Statistic to calculate (count/mean/median/mode/std/etc.)
397
    - center: Center bins on coordinates
398
    - empty: Value for empty bins
399
    
400
    Returns:
401
    pandas.DataFrame: Binned statistics
402
    """
403

404
def dimfilter(grid: PathLike | xr.DataArray, **kwargs):
405
    """
406
    Directional median filter for grids.
407
    
408
    Parameters:
409
    - grid: Input grid file or xarray DataArray
410
    - filter: Filter specification (type and parameters)
411
    - distance: Filter distance/width
412
    - geometry: Filter geometry (rectangular/circular)
413
    - nans: How to handle NaN values
414
    
415
    Returns:
416
    xarray.DataArray: Filtered grid
417
    """
418

419
def filter1d(data: PathLike | TableLike | None = None, **kwargs):
420
    """
421
    Apply a time domain filter to 1-D time series.
422
    
423
    Parameters:
424
    - data: Input time series data
425
    - filter: Filter type and parameters
426
    - output_format: Output format specification
427
    - time_col: Time column specification
428
    - robust: Use robust filtering
429
    
430
    Returns:
431
    pandas.DataFrame: Filtered time series
432
    """
433
```
434

435
### Coordinate and Projection Operations
436

437
Transform coordinates and project data between coordinate systems.
438

439
```python { .api }
440
def project(data: PathLike | TableLike | None = None, **kwargs):
441
    """
442
    Project/transform coordinates.
443
    
444
    Parameters:
445
    - data: Input coordinate data
446
    - center: Projection center coordinates
447
    - projection: Projection type
448
    - length_scale: Length scale for projection
449
    - width_scale: Width scale for projection  
450
    - inverse: Perform inverse transformation
451
    - ellipsoid: Reference ellipsoid
452
    - unit: Distance units
453
    
454
    Returns:
455
    pandas.DataFrame: Transformed coordinates
456
    """
457

458
def grdtrack(data: PathLike | TableLike | None = None, grid: PathLike | xr.DataArray | None = None, 
459
             **kwargs):
460
    """
461
    Sample grids at specified (x,y) locations.
462
    
463
    Parameters:
464
    - data: Input coordinate file or table (x, y columns)
465
    - grid: Grid file(s) or xarray DataArray(s) to sample
466
    - newcolname: Name for new columns with sampled values
467
    - no_skip: Do not skip points outside grid domain
468
    - radius: Search radius for nearest point
469
    - bicubic: Use bicubic interpolation
470
    
471
    Returns:
472
    pandas.DataFrame: Input coordinates with sampled grid values
473
    """
474

475
def select(data: PathLike | TableLike | None = None, **kwargs):
476
    """
477
    Select data subset based on multiple criteria.
478
    
479
    Parameters:
480
    - data: Input data file or table
481
    - region: Geographic region selection
482
    - condition: Conditional expression for selection
483
    - reverse: Reverse the selection (select NOT matching)
484
    - polygon: Select points inside/outside polygon
485
    - distance: Distance-based selection criteria
486
    - connect: Connect selection criteria with AND/OR
487
    
488
    Returns:
489
    pandas.DataFrame: Selected data subset
490
    """
491
```
492

493
### Color Palette and Configuration
494

495
Create and modify color palettes for visualization.
496

497
```python { .api }
498
def makecpt(**kwargs):
499
    """
500
    Make GMT color palette tables.
501
    
502
    Parameters:
503
    - cmap: Master color palette table to use
504
    - series: Define z-value range for new CPT ([min, max, inc])
505
    - reverse: Reverse color progression
506
    - truncate: Truncate incoming CPT range
507
    - background: Select background/foreground colors
508
    - output: Output filename for CPT file
509
    - overrule_bg: Overrule background colors from master CPT
510
    - continuous: Force continuous CPT
511
    - no_bg: Don't write background/foreground/NaN colors
512
    - transparency: Set transparency level (0-100)
513
    - categorical: Use categorical color table
514
    - cyclic: Produce wrapped/cyclic color table
515
    - color_model: Force output CPT color model (RGB/HSV/CMYK)
516
    - log: Use logarithmic interpolation
517
    
518
    Returns:
519
    str: Color palette table data
520
    """
521
```
522

523
### Cross-Track Analysis
524

525
Analyze intersections between track data files.
526

527
```python { .api }
528
def x2sys_init(tag: str, **kwargs):
529
    """
530
    Initialize a new x2sys track database.
531
    
532
    Parameters:
533
    - tag: Database tag name
534
    - suffix: File suffix for track files
535
    - format: Track file format specification
536
    - region: Default region for database  
537
    - projection: Default projection
538
    - units: Distance and speed units
539
    - gap: Maximum gap between data points
540
    
541
    Returns:
542
    None: Creates database files
543
    """
544

545
def x2sys_cross(tracks: PathLike | list | None = None, **kwargs):
546
    """
547
    Calculate crossovers between track data files.
548
    
549
    Parameters:
550
    - tracks: Track file(s) or list of files
551
    - tag: x2sys database tag
552
    - region: Geographic region for crossover search
553
    - interpolation: Interpolation method at crossovers
554
    - coe: Crossover error calculation method
555
    - track_output: Output individual track crossovers
556
    - speed: Speed column for time-based interpolation
557
    
558
    Returns:
559
    pandas.DataFrame: Crossover analysis results
560
    """
561
```
562

563
## Usage Examples
564

565
### Basic Gridding
566

567
```python
568
import pygmt
569
import numpy as np
570

571
# Create sample irregular data
572
np.random.seed(42)
573
x = np.random.uniform(-5, 5, 100)
574
y = np.random.uniform(-5, 5, 100) 
575
z = x**2 + y**2
576

577
# Grid the data using surface method
578
grid = pygmt.surface(
579
    data=np.column_stack([x, y, z]),
580
    region=[-5, 5, -5, 5],
581
    spacing=0.1,
582
    tension=0.25
583
)
584

585
print(f"Grid shape: {grid.shape}")
586
print(f"Grid extent: {grid.gmt.registration}")
587
```
588

589
### Grid Processing Chain
590

591
```python
592
import pygmt
593

594
# Load a sample grid
595
grid = pygmt.datasets.load_earth_relief(resolution="05m", region=[120, 160, 20, 50])
596

597
# Apply a smoothing filter
598
filtered = pygmt.grdfilter(
599
    grid=grid,
600
    filter="g50k",  # Gaussian filter with 50 km width
601
    distance="50k"
602
)
603

604
# Calculate gradients
605
gradients = pygmt.grdgradient(
606
    grid=filtered,
607
    azimuth=45,     # Northeast direction
608
    normalize="e"   # Normalize by illumination
609
)
610

611
# Clip extreme values
612
clipped = pygmt.grdclip(
613
    grid=gradients,
614
    above=0.8,
615
    below=-0.8,
616
    new_high=0.8,
617
    new_low=-0.8
618
)
619
```
620

621
### Block Processing
622

623
```python
624
import pygmt
625
import pandas as pd
626

627
# Load sample data
628
data = pd.DataFrame({
629
    'longitude': [120.5, 120.6, 120.7, 120.5, 120.6],
630
    'latitude': [25.1, 25.2, 25.1, 25.3, 25.4],  
631
    'elevation': [100, 150, 120, 200, 180]
632
})
633

634
# Block average the data
635
block_avg = pygmt.blockmean(
636
    data=data,
637
    region=[120, 121, 25, 26],
638
    spacing="0.1d",  # 0.1 degree blocks
639
    registration="g"  # Gridline registration
640
)
641

642
print(block_avg.head())
643
```
644

645
### Track Sampling
646

647
```python
648
import pygmt
649
import numpy as np
650

651
# Create a sample track
652
track_lon = np.linspace(130, 140, 50)
653
track_lat = np.linspace(30, 35, 50)
654
track = np.column_stack([track_lon, track_lat])
655

656
# Load elevation grid
657
grid = pygmt.datasets.load_earth_relief(resolution="01m", region=[129, 141, 29, 36])
658

659
# Sample grid along track
660
sampled = pygmt.grdtrack(
661
    data=track,
662
    grid=grid,
663
    newcolname="elevation"
664
)
665

666
print(f"Track points: {len(sampled)}")
667
print(f"Columns: {sampled.columns.tolist()}")
668
```