spatialmerge

A (relatively) fast library for spatial joining and merging data in JavaScript.

The library is largely influenced by the geopandas merge and sjoin methods. Just as geopandas, spatialmerge utilizes a static spatial index provided by Flatbush (R-tree) to narrow down the number of features to test for intersection.

import { merge, sjoin } from 'spatialmerge'
// join the properties of a spatial dataset (GeoJSON FeatureCollection) with a
// non-spatial dataset (e.g. contents of a CSV file parsed using d3-dsv) 
// based on a common variable
const resultsMerge = merge(countryShapes, countryNames, { on: 'iso_a3' })

// join the properties of two spatial datasets (GeoJSON FeatureCollections)
const mergeSjoin = sjoin(citiesPoints, countryShapes)

Working examples, and an in-depth explanation of the two functions can be found in the user guide notebook.

Installing

npm install spatialmerge
# or
yarn add spatialmerge

For vanilla HTML in modern browsers, import spatialmerge from Skypack:

<script type="module">

import { merge, sjoin } from 'https://cdn.skypack.dev/spatialmerge'
// ...

</script>

For legacy environments, you can load spatialmerge’s UMD bundle from an npm-based CDN such as jsDelivr; a spatialmerge global is exported:

<script src="https://cdn.jsdelivr.net/npm/spatialmerge"></script>

User Guide

The User Guide is hosted as an interactive ObservableHQ notebook
https://observablehq.com/@chrispahm/hello-spatialmerge

API reference

spatialmerge.merge(leftFC, rightFC_or_arrayOfObjects, options = { on: <property>, mutate: false }])

Join the attributes of a GeoJSON FeatureCollection with an array of objects or another GeoJSON FeatureCollection based on a common variable (object key).

Parameters:

leftFC: <GeoJSON FeatureCollection>, required
rightFC_or_arrayOfObjects: <GeoJSON FeatureCollection> OR <array of objects>, required
options: <object>, required
- on: <string>, required
  The key to join the two collections on.
- mutate: <boolean>, default: false
  Allows GeoJSON input to be mutated (significant performance increase if true)

spatialmerge.sjoin(leftFC, rightFC[, options = { how: 'inner', op: 'intersects', matches: 'all', lsuffix: 'left', rsuffix: 'right' }])

Spatial join of two GeoJSON FeatureCollections.
See the User Guide for details.

Parameters:

leftFC, rightFC: <GeoJSON FeatureCollection>, required
options: <object>, optional
- how: <string>, default: 'inner'
  The type of join:
  - ‘left’: use keys from left_df; retain only left_df geometry column
  - ‘right’: use keys from right_df; retain only right_df geometry column
  - ‘inner’: use intersection of keys from both dfs; retain only left_df geometry column
- op: <string>, default: 'intersects'
  Binary predicate. Internally uses the corresponding turf.js modules.
  - 'intersects'
  - 'contains'
  - 'within'
  - 'crosses'
  - 'overlaps'
- matches: <string>, default: 'all' Whether to output all results of the join operation, or only the first.
  - 'all'
  - 'first'
- lsuffix: <string>, default: 'left'
  Suffix to apply to overlapping column names (left GeoJSON).
- rsuffix: <string>, default: 'right'
  Suffix to apply to overlapping column names (right GeoJSON).
- inclLeftIndex: <boolean>, default: false
  Whether to include the left index as a property value in the resulting GeoJSON FeatureCollection.

Performance

Spatially merging datasets is (almost) always a computationally intensive task. If you plan to use spatialmerge on the client side or in a Node.js / Deno server, be sure to wrap it in a WebWorker or worker_thread to avoid blocking the Rendering / Event Loop.

Resources:

TODOs

Fix tests for sjoin including large files, potentially using git-lfs
Example using WebWorker
Performance comparison with @turf/tag and geopandas

Contribution

Contribution is highly appreciated 👍
Please open an issue in case of questions / bug reports or a pull request if you implemented a new feature / bug fix. In the latter case, please make sure to run npm test (and adapt test/test.js to your changes) and / or update the README 🙂

License

MIT @Christoph Pahmeyer

brahn/spatialmerge