Skip to main content

AdarvMaps

Interactive epidemiological spot maps for India — no GIS software, no shapefiles, no setup.

PyPI version Python versions License: MIT

AdarvMaps turns a spreadsheet of latitude and longitude from the field into a polished, interactive HTML map. You can open the map in any browser, personalise it, and download it as a PNG image or a PDF. AdarvMaps already has India's state and district boundaries built in, so you don't have to search for shapefiles.


Preparing your data

Please ensure each row in your spreadsheet is one person or event, and that each row carries its location (latitude and longitude) in separate columns. You may also include an extra column that splits the data into case and control (a grouping variable), if you want to show both on the same map.


What will AdarvMaps do?

AdarvMaps turns your spreadsheet into an interactive map. It automatically places every row as a dot at its location, draws the correct state and district boundaries for you, and colours the two groups differently. It then generates a single, self-contained HTML file you can open in any browser to personalise your map, download as a PNG or PDF, or email to a colleague. You can also aggregate the dots to switch from a spot map to a dot-density map.

With AdarvMaps you can make:

  • 📍 Spot maps — show the location of individual people or events
  • 🔴 Dot-density maps — show the clustering of cases

Which guide is for me?

If this sounds like you… Go to
🙋 "I just want a map — I don't write code." → Guide for non-coders
👩‍💻 "I write Python and want the API / command line." → Guide for developers

Guide for non-coders

This guide is for anyone who wants to create a map but has never written any code. You don't need to install anything on your computer, and you don't need to understand any programming. We'll give you the template code to copy and paste, and then AdarvMaps guides you through the rest with a few simple, plain-English questions.

Step 1 — Open a free notebook

Go to colab.research.google.com and click New notebook. Google Colab is a free service that runs code in your web browser, so there's nothing to install. You'll see an empty box called a cell.

Step 2 — Start AdarvMaps

Click inside the cell, paste the two lines below, and press the ▶ (play) button on the left:

!pip install adarvmaps
import adarvmaps; adarvmaps.run()

The first line installs AdarvMaps; the second starts the guided wizard. Depending on your internet speed, this may take a little while.

Step 3 — Answer the questions

AdarvMaps asks five questions. For each one it shows its own best guess — if the guess is right, just press Enter to accept it; otherwise, type the number of the correct choice.

1. Upload your data file

  • In Jupyter Notebook, VS Code, or Google Colab, an Upload button appears — click it and pick your spreadsheet (CSV, Excel .xlsx / .xls, or TSV) from your computer.
  • AdarvMaps then prints a quick summary — how many rows and columns it found, each column name with an example value, and the first few rows — so you can confirm the file was read correctly.
  • Please note: on Google Colab, your data is temporarily uploaded to Google's servers. In Jupyter Notebook, VS Code, or similar software on your own computer, the data stays on your system and is not shared anywhere.

2. Which column has the latitude?

  • Latitude is the north–south number (for example, 28.61 for Delhi).
  • AdarvMaps pre-selects the column it thinks is the latitude. If the guess is correct, press Enter to accept; otherwise, check the summary above and type the number of the right column.

3. Which column has the longitude?

  • Longitude is the east–west number (for example, 77.20 for Delhi).
  • AdarvMaps pre-selects the column it thinks is the longitude. If the guess is correct, press Enter to accept; otherwise, check the summary above and type the number of the right column.
  • Remember: if the points later look misplaced, the most common mistake is that latitude and longitude are swapped.

4. Which column is your grouping variable?

  • If your spreadsheet has a variable that splits the data into cases and controls, or affected and not affected, choose it here — we call this the grouping variable.
  • You can equally use this to show males and females, dead and alive, or positive and negative differently on the map.
  • If you don't want any split, choose the first option: My data is all cases (no control group).

5. Which value is the main group?

  • AdarvMaps lists the values found in the grouping variable you chose in question 4.
  • Tell it which value is the main group (the highlighted / clustered group). For example, if you coded 1 = Case, 0 = Control or Yes = Case, No = Control, choose 1 or Yes.
  • Every other value becomes the other group, shown with its own name from your data.

Once you've answered all five, AdarvMaps builds the map as an HTML file.

Step 4 — Get your map

  • Your map appears right below the cell and is also saved as a file (e.g. adarvmaps_200926.html).
  • Download it and open it in any browser, or email it to a colleague — it's a single self-contained file (an internet connection is needed to load the background map tiles).
  • Using the map's sidebar you can:
    • Switch between the Spot Map and the Dot-Density Map
    • Show one group or both
    • Change the colours of the dots and resize them
    • Turn place-name labels on or off
    • Save the map as a PNG image or PDF

Guide for developers

Step 1 — Install

pip install adarvmaps

Python 3.9+.

Step 2 — Use it

from adarvmaps import AdarvMaps

# `data` accepts a CSV path or a pandas DataFrame
AdarvMaps("my_data.csv").build().save("map.html")

Or from the command line (run adarvmaps with no arguments for the guided wizard):

adarvmaps my_data.csv -o map.html

Python API reference

AdarvMaps(
    data,                      # required: a CSV path or a pandas DataFrame
    state_shp=None,            # custom state boundary (shapefile / GeoPackage)
    district_shp=None,         # custom district boundary
    lat_col=None,              # override column auto-detection
    long_col=None,
    outcome_col=None,          # the grouping column
    case_value=None,           # which value in outcome_col is the main group
    case_label=None,           # name for the main group (default: the data's own value)
    control_label=None,        # name for the other group (default: the data's own value)
    all_cases=False,           # treat every row as a case (no second group)
    count_cutoff=2,            # districts ≤ cutoff → district-level zoom
    margin_deg=1.0,            # boundary crop padding
    cluster_color="#E85252",   # dot-density bubble colour
    case_color="#D55757",      # main-group pin colour
    control_color="#7676E7",   # other-group pin colour
)

Common options

AdarvMaps(data, ...) — all options below are keyword arguments:

Option Default Description
lat_col, long_col, outcome_col auto Override column auto-detection
case_value auto Value in outcome_col that is the main group
case_label, control_label data values Names shown for the two groups on the map
all_cases False Treat every row as a case (no second group)
case_color, control_color, cluster_color ADARV palette Marker colours (hex)
state_shp, district_shp bundled Use your own boundary files

Full API and CLI reference → DOCUMENTATION.md


Extra notes

Preparing your data (details)

AdarvMaps reads a CSV and auto-detects the columns — you don't have to rename anything. At a minimum it needs location, and optionally a grouping column:

What AdarvMaps needs Possible column names How to provide it
Coordinates lat, lon (or latitude, longitude) Separate lat / lon columns, or one combined "lat,lon" column
Grouping (optional) outcome, status, case_control, case A column with two values, e.g. case / control

Example:

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

What you get

A single, self-contained HTML file you can open in any browser or share. Its sidebar lets anyone switch between Dot Density and Spot Pins, show one group or both, recolour and resize markers, toggle place-name labels, and export to PNG / PDF.


ADARV Team

AdarvMaps is developed by the ADARV team:

  1. Muniraj Mallesan (Maintainer)
  2. Dr. Sharan Murali (Team Lead)
  3. Manikandan K
  4. Shanmuga Sundharam
  5. Yogita Chaudhary
  6. Barath U
  7. Balaji S
  8. Deepana R

License

MIT © ADARV

Metadata

Release files for adarvmaps 0.1.42

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

Source distribution (sdist)

Source distribution for adarvmaps 0.1.42
File Size Uploaded Provenance Actions
adarvmaps-0.1.42.tar.gz 1.9 MB Without provenance Details for adarvmaps-0.1.42.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for adarvmaps 0.1.42
File Interpreter ABI Platform Actions
adarvmaps-0.1.42-py3-none-any.whl Python 3 none any Details for adarvmaps-0.1.42-py3-none-any.whl

Total release size: 3.8 MB

Release files / adarvmaps-0.1.42.tar.gz

Download URL adarvmaps-0.1.42.tar.gz
Size 1.9 MB
Tags Source
SHA-256 checksum
How to use checksums
6222dca08465361b32f8faab6074adb8c5eb4503e012bbc09cb2adc7e4ef779f
BLAKE2b-256 checksum
How to use checksums
c480985e7115427395a99fe050034a84f553752d4833bbe750a44a6443dbe3f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.3

Release files / adarvmaps-0.1.42-py3-none-any.whl

Download URL adarvmaps-0.1.42-py3-none-any.whl
Size 1.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
27738b851242167c6e9bd4a8941b7b48de65779c88b056ff50553b3f57950ea7
BLAKE2b-256 checksum
How to use checksums
0657c8d7f910e72124afaba69def1aaa74f41173783ee5631349e846dfc7c454
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.3

Security for adarvmaps 0.1.42

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page