geoclustering

📍 command-line tool for clustering geolocations.

Features

• Uses DBSCAN or OPTICS to perform clustering.
• Outputs clustering results as json, txt and geojson.
• Creates a kepler.gl visualization of clusters.

Clustering Method

A cluster is created when a certain number of points (=> --size) each are within a given distance (=> --distance) of at least one other point in the cluster.

Install

Install with pip:

pip install geoclustering

If the install fails, you might need to install kepler.gl build dependencies:

# macos
brew install proj gdal

Usage

Usage: geoclustering [OPTIONS] FILENAME

  Tool to cluster geolocations. A cluster is created when a certain number of
  points (--size) each are within a given distance (--distance) of at least
  one other point in the cluster. Input is supplied as a csv file. At a
  minimum, each row needs to have a 'lat' and a 'lon' column. Other rows are
  reflected to the output.

Options:
  -d, --distance FLOAT            (in km) Max. distance between two points in
                                  a cluster.  [required]
  -s, --size INTEGER              Min. number of points in a cluster.
                                  [required]
  -o, --output PATH               Output directory for results. Default:
                                  ./output
  -a, --algorithm [dbscan|optics]
                                  Clustering algorithm to be used. `optics`
                                  produces tighter clusters but is slower.
                                  Default: dbscan
  --open                          Open the generated visualization in the
                                  default browser automatically.
  --debug                         Print debug output.
  --help                          Show this message and exit.

Input

Inputs are supplied as a .csv file. The only required fields are lat and lon, all other fields are reflected to the output.

id,name,lat,lon
1,Bonnibelle Mathwen,40.1324085,64.4911086
...

Output

If at least one cluster was found, the tool outputs a folder with output as json, geojson, txt files. A kepler.gl html file is generated as well.

JSON

Encodes an array of clusters, each containing an array of points.

[
  {
    "cluster_id": 0,
    "points": [
      {
        "id": 9,
        "name": "Rosanna Foggo",
        "lat": -6.2074293,
        "lon": 106.8915948
      }
    ]
  }
]

GeoJSON

Encodes a single FeatureCollection, containing all points as Feature objects.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          106.891595,
          -6.207429
        ]
      },
      "properties": {
        "id": 9,
        "name": "Rosanna Foggo",
        "cluster_id": 0
      }
    }
  ]
}

Text

Encodes cluster as blocks separated by a newline, where each line in a cluster block contains one point.

Cluster 0
id 9, name Rosanna Foggo, lat -6.2074293, lon 106.8915948

// ...

kepler.gl

Develop

It is assumed that you are using Python3.9+. It is encouraged to setup a virtualenv for development.

    # install dependencies & dev-dependencies
    pip install -e .[dev]

    # install a git hook that runs the code formatter before each commit.
    pre-commit install

We use Black as our code formatter. If you don't want to use the pre-commit hook, you can run the formatter manually or via an editor plugin.