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 this HTML map in any browser, make the necessary edits, and then download it as a PNG image or a PDF. AdarvMaps already has India's state and district boundaries built in, so that you don't have to search for shapefiles.

Preparing data for AdarvMaps

Please ensure that each row in your spreadsheet corresponds to one person or event. Each of these rows should also have its location (latitude and longitude) in separate columns. You may also have extra columns in your spreadsheet indicating whether the person is a case or a control (grouping variable), if you intend to show both on the same map.

What will AdarvMaps do?

AdarvMaps will turn your spreadsheet into an interactive map. AdarvMaps will automatically place every row as a "dot" at its location on the map, draw the correct state and district boundaries for you, and colour cases and controls differently. AdarvMaps will then generate an interactive HTML file that you can open in your browser to personalise your map, and you can download it as a PNG or PDF. You may also aggregate the dots and convert the spot map into a dot-density map. The result is a single web page (HTML) you can open in any browser or email to a colleague.

With AdarvMaps, you can generate maps with the following features:

  • Spot maps for showing the location of individuals/events
  • Dot-density map to show 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 will give you the template code, which you can copy and paste. After this, the package will guide you through the remaining steps 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 is nothing to install on your computer. 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 of the cell:

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

The first line installs AdarvMaps; the second line starts the guided wizard. Based on your internet speed, this step will take some time.

Step 3 — Answer the questions

AdarvMaps will now ask 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.

Here is every question you'll see and what it means:

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 your file was read correctly.
  • Please note: If you are running the package on Google Colab, your data will be temporarily uploaded to Google's servers (until the Colab session is active). However, if you are working in Jupyter Notebook, VS Code, or similar software, the data will remain within your system and won't be shared outside.

2. Which column has the latitude?

  • Latitude is the north–south number (for example, 28.61 for Delhi).
  • AdarvMaps will pre-select the column that it thinks is the latitude. If AdarvMaps' guess is correct, press Enter to accept.
  • If the guess is wrong, check the quick summary generated 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 will pre-select the column that it thinks is the longitude. If AdarvMaps' guess is correct, press Enter to accept.
  • If the guess is wrong, check the quick summary generated above, and type the number of the right column.
  • Remember: if the points later look misplaced, the most common mistake is that the latitude and longitude may be swapped.

4. Which column has the grouping variable?

  • If your spreadsheet has a variable that splits the data into "cases" and "controls," or into "affected" and "not affected," then you may choose that variable here. Let's call it the Grouping Variable.
  • Alternatively, if you want to show "males" and "females," "dead" and "alive," "positive" and "negative" differently on the map, then you may also use this option.
  • If you don't want to show any groups on the map, choose the first option: "My data is all cases (no control group)."

5. Which value marks the outcome?

  • AdarvMaps will now show the values from the spreadsheet for the grouping variable that you chose in question 4.
  • Please tell AdarvMaps which of the listed values refer to the "case."
  • For example, you may have coded your spreadsheet as 1 = Case and 0 = Control, or Yes = Case, No = Control. AdarvMaps will now ask for the value you used to represent a case. In this case, you can choose 1 or Yes.
  • Every other value is treated as a control.

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

Step 4 — Getting the Map!

  • Your map appears right below the cell and is also saved as a file (for example, adarvmaps_281026.html).
  • Download it and open it in any browser — it is a single self-contained file (an internet connection is needed to load the background map tiles).
  • Using the map's sidebar, you can make the following edits:
    • Switch between the Spot Map and the Dot-Density Map
    • Hide "controls"
    • Change the colours of the dots, and resize them
    • Turn place-name labels on or off, and finally
    • Save the map as a PNG image or PDF.

Guide for developers

Step 1: Installing the package

pip install adarvmaps

Step 2: Running the package

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:

adarvmaps my_data.csv -o map.html

A fuller example (overriding the automatic choices):

AdarvMaps(
    "cases.csv",
    lat_col="Latitude",
    long_col="Longitude",
    outcome_col="vital_status",
    case_value="dead",
    case_label="Deaths",
    control_label="Survivors",
    case_color="#B00020",
    control_color="#0057B7",
).build().save("map.html")

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 means "case"
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 controls)
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

AdarvMaps reads a CSV and auto-detects the columns. You don't have to rename anything. At a minimum, it needs the following variables:

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 values like 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 groups, recolour markers, resize pins, 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.43

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.43
File Size Uploaded Provenance Actions
adarvmaps-0.1.43.tar.gz 1.9 MB Without provenance Details for adarvmaps-0.1.43.tar.gz

Built distribution (wheel)

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

Total release size: 3.8 MB

Release files / adarvmaps-0.1.43.tar.gz

Download URL adarvmaps-0.1.43.tar.gz
Size 1.9 MB
Tags Source
SHA-256 checksum
How to use checksums
13a9de3d5fda867d7dca32ed433c2a1e612089453e65ac5c44b5dae96cd69ba4
BLAKE2b-256 checksum
How to use checksums
c53e922e34714be7c83791e0a65405fd8f2bc9ce7bc5ab847f78709279dcc07d
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.43-py3-none-any.whl

Download URL adarvmaps-0.1.43-py3-none-any.whl
Size 1.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
c0bae2899228eb2d0b1948cd011985d667954ad35c7b12a422b0d66d299db2e3
BLAKE2b-256 checksum
How to use checksums
b5b836f06f4844e45c874a74c3465d6f507ee392c4a895b62e78012feca99993
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.43

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