SpotMap

Interactive epidemiological spot maps for India

SpotMap turns a CSV of case/control coordinates into a publication-ready interactive HTML map with:

Dot density clustering (cases only)
Spot map pins (cases and/or controls) with custom colours
Automatic state/district boundary overlays (bundled data — no shapefile setup needed)
Sidebar with mode toggle, colour pickers, pin size slider, and PNG/PDF export
Smart auto-detection of latitude, longitude, and outcome columns

Installation

pip install spotmap

Quick start

Interactive (no coding required)

The easiest way — works great in Google Colab or a Jupyter notebook. Install it, then run these two lines:

!pip install spotmap

import spotmap
spotmap.run()

SpotMap then walks you through a few simple prompts:

Upload your data file (in Colab an upload button appears; elsewhere it asks for the file path).
Confirm which columns hold latitude, longitude, and the case/control outcome (SpotMap pre-selects its best guess).
Pick which value means "case".

The finished map is shown right in the notebook cell — no need to hunt for a file — and is also saved as spotmap.html (pass a different name with spotmap_run("my_map.html")).

In a plain terminal, spotmap_run() reads your answers from the keyboard and saves an HTML file to open in your browser. For automated scripts, use the Python API below instead.

Python API

from spotmap import SpotMap

SpotMap("my_data.csv").build().save("map.html")

Command line

spotmap my_data.csv -o map.html

CSV format

SpotMap auto-detects columns — no strict naming required.

Requirement	Details
Coordinates	Separate `lat` / `lon` columns or a combined `"lat,lon"` column
Outcome	A column named `outcome`, `status`, `case_control`, etc. with values like `case` / `control`

Example:

latitude,longitude,outcome
28.6,77.2,case
19.0,72.8,control
13.0,80.2,case

Python API reference

SpotMap(
    csv_path,                       # required
    state_shp=None,                 # custom state boundary (shapefile/GeoPackage)
    district_shp=None,              # custom district boundary
    lat_col=None,                   # override auto-detection
    long_col=None,
    outcome_col=None,
    case_value=None,                # value that means "case" in outcome_col
    count_cutoff=2,                 # districts ≤ cutoff → district zoom
    margin_deg=1.0,                 # boundary crop padding
    cluster_color="#E85252",        # dot-density bubble colour
    case_color="#D55757",           # case pin colour
    control_color="#7676E7",        # control pin colour
)

Chain calls:

sm = SpotMap("data.csv", case_color="#FF0000").build()
sm.save("map.html")

# Access the raw Folium map for further customisation
folium_map = sm.map

CLI reference

usage: spotmap [-h] [-o OUTPUT] [--state-shp STATE_SHP]
               [--district-shp DISTRICT_SHP] [--lat-col LAT_COL]
               [--lon-col LON_COL] [--outcome-col OUTCOME_COL]
               [--case-value CASE_VALUE] [--count-cutoff COUNT_CUTOFF]
               [--cluster-color CLUSTER_COLOR] [--case-color CASE_COLOR]
               [--control-color CONTROL_COLOR]
               csv

Team

SpotMap is developed by the ADARV team:

Name	Role
Muniraj Mallesan	Maintainer
Dr. Sharan Murali	Team Lead
Manikandan K
Shanmuga Sundharam
Yogita Chaudhary
Barath U
Balaji S
Deepana R

License

MIT © ADARV

Release files for spotmap 0.1.33

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spotmap 0.1.33
File	Size	Uploaded
spotmap-0.1.33.tar.gz	1.9 MB	Jul 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for spotmap 0.1.33
File	Interpreter	ABI	Platform	Reset
spotmap-0.1.33-py3-none-any.whl 1.9 MB Jul 23, 2026	Python 3	none	any	Details

Total release size: 3.8 MB

Release files / spotmap-0.1.33.tar.gz

Download URL	spotmap-0.1.33.tar.gz
Size	1.9 MB
Tags	Source
SHA-256 checksum How to use checksums	`6e8c5a7a5a44e4171df84c7b9c2875765241e2410b53ca985e5ffed1eec2aa3e`
BLAKE2b-256 checksum How to use checksums	`db4e1360907fc7230e7004bc4d300edfe6a8183e87df75eb37ed106cde0fb28c`
Upload date	Jul 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.3`

Release files / spotmap-0.1.33-py3-none-any.whl

Download URL	spotmap-0.1.33-py3-none-any.whl
Size	1.9 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`64831e065636e12906dc78fc546afb2c2939df55429b87e600cd60b550abceb6`
BLAKE2b-256 checksum How to use checksums	`0483b8e96e54efa3d6bb7a8b772809cfc18790ca20cb3397f895a8c7ee14ae5e`
Upload date	Jul 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.3`