geoenrich 0.7.0

Enrich longitude/latitude points with coast distance, bathymetric depth, sea name, and nearest country/municipality
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# nearest

Nearest location in a second table you supply, with the distance to it.

```bash
geoenrich nearest <INPUT> --to <REFERENCE> [OPTIONS]
```

Unlike the other commands, the reference data is not a bundled dataset but a
second table you pass with `--to`: any set of named locations (fish farms,
ports, stations). For every input point it appends the name of the nearest
reference location and the great-circle distance to it.

Appends two columns:

| Column | Meaning |
|--------|---------|
| `nearest_name` | Name of the nearest reference location (rename with `--name-column`) |
| `nearest_dist` | Distance to it, in km (default) or m (rename with `--dist-column`) |

## How it works

Every reference point is mapped to a unit-sphere `(x, y, z)` vector and indexed
in a 3D R-tree. Each input point is projected the same way and takes the R-tree's
nearest neighbor. Euclidean chord distance on the unit sphere grows monotonically
with the great-circle distance, so the nearest by chord is the nearest on the
globe; the chord is then converted back to meters.

The unit sphere is used instead of the region LAEA on purpose: the two sets can
be anywhere and arbitrarily far apart, and a single planar projection distorts
distances away from its center. The sphere is exact everywhere, so this command
takes no region box or projection center. Reference rows with a missing
coordinate are skipped; an empty reference set leaves every output null.

## Options

Beyond the [shared options](../reference/configuration.md):

| Option | Default | Meaning |
|--------|---------|---------|
| `--to <FILE>` | required | Reference table: the second set of locations |
| `--to-format <FMT>` | inferred | Format of the reference table |
| `--to-lon-col <NAME>` | `longitude` | Longitude column in the reference table |
| `--to-lat-col <NAME>` | `latitude` | Latitude column in the reference table |
| `--name-field <NAME>` | `name` | Column in the reference table holding each location's name |
| `--unit <km\|m>` | `km` | Distance unit for the output distance column |
| `--name-column <NAME>` | `nearest_name` | Output column for the nearest name |
| `--dist-column <NAME>` | `nearest_dist` | Output column for the distance |

## Example

```bash
# Nearest fish farm to each measurement, distance in km
geoenrich nearest cores.parquet --to farms.parquet \
  --name-field farm_name -o cores.nearest.parquet
```

The name column is cast to text, so numeric ids work as names too.