AdarvMaps
Interactive epidemiological spot maps for India — no GIS software, no shapefiles, no setup.
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.61for 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.20for 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 = ControlorYes = Case, No = Control, choose1orYes. - 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:
- Muniraj Mallesan (Maintainer)
- Dr. Sharan Murali (Team Lead)
- Manikandan K
- Shanmuga Sundharam
- Yogita Chaudhary
- Barath U
- Balaji S
- 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.