Metadata-Version: 2.5
Name: adarvmaps
Version: 0.1.41
Summary: Interactive epidemiological spot maps for India
Project-URL: Homepage, https://github.com/ADARV-Epi-hub/adarvmaps
Project-URL: Repository, https://github.com/ADARV-Epi-hub/adarvmaps
Project-URL: Bug Tracker, https://github.com/ADARV-Epi-hub/adarvmaps/issues
Author: Muniraj Mallesan, Dr. Sharan Murali, Manikandan K, Shanmuga Sundharam, Yogita Chaudhary, Barath U, Balaji S, Deepana R
Maintainer-email: Muniraj Mallesan <adarv@nieicmr.org.in>
License: MIT License
        
        Copyright (c) 2025 ADARV
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: AUTHORS.md
License-File: LICENSE
Keywords: case-control,epidemiology,folium,geospatial,india,spot map
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.9
Requires-Dist: folium>=0.14
Requires-Dist: geopandas>=0.13
Requires-Dist: numpy>=1.24
Requires-Dist: openpyxl>=3.1
Requires-Dist: pandas>=2.0
Requires-Dist: shapely>=2.0
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# AdarvMaps

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

[![PyPI version](https://img.shields.io/pypi/v/adarvmaps.svg)](https://pypi.org/project/adarvmaps/)
[![Python versions](https://img.shields.io/pypi/pyversions/adarvmaps.svg)](https://pypi.org/project/adarvmaps/)
[![License: MIT](https://img.shields.io/pypi/l/adarvmaps.svg)](https://github.com/ADARV-Epi-hub/adarvmaps/blob/main/LICENSE)

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, make edits, and download it as
a **PNG** image or **PDF**. India's state and district boundaries are already built in, so
you don't have to search for shapefiles.

- 📍 **Spot maps** — show the location of individual people or events
- 🔴 **Dot-density maps** — aggregate nearby points to show clustering of cases
- 🗺️ Built-in **state & district boundaries** — nothing to download
- 🎨 Recolour and resize markers, toggle place-name labels, export to PNG / PDF
- 🤖 **Auto-detects** your latitude / longitude / outcome columns

---

## 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**, and
colours the groups (e.g. cases and controls) differently. It then generates a single,
self-contained **HTML** file you can open in any browser to fine-tune your map — and you
can download it as a PNG or PDF, or email it to a colleague. You may also aggregate the
dots to switch from a spot map to a **dot-density** map.

---

## 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](#guide-for-non-coders) |
| 👩‍💻 **"I write Python and want the API / command line."** | → [Guide for developers](#guide-for-developers) |

Everyone should also read [Preparing your data](#preparing-your-data) first.

---

## Preparing your data

Each **row** in your spreadsheet should be **one person or event**, and each row should
carry its **location** (latitude and longitude) in separate columns. You may also include
an extra column that splits the data into groups (e.g. case / control) if you want to show
both on the same map.

---

## Guide for non-coders

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

### Step 1 — Open a free notebook
Go to **[colab.research.google.com](https://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:
```python
!pip install adarvmaps
import adarvmaps; adarvmaps.run()
```
The first line installs AdarvMaps; the second starts the guided wizard. Depending on your
internet speed, the install may take a little while.

### Step 3 — Answer the questions
AdarvMaps asks **five** questions. Each shows its own best guess — press **Enter** to
accept it, or type the number of the correct choice.

1. **Upload your data file**
   - In Colab (or Jupyter / VS Code) an *Upload* button appears — click it and pick your
     spreadsheet (CSV, Excel `.xlsx` / `.xls`, or TSV).
   - AdarvMaps prints a quick summary — the number of rows and columns, each column name
     with an example value, and the first few rows — so you can confirm it read your file.
   - **FAQ: Is my data uploaded to a server?** On **Colab**, yes — Colab runs on Google's
     cloud, so your file is processed on Google's servers (see the privacy note below). If
     your data must stay private, **run AdarvMaps locally** instead (see Guide for
     developers) — nothing leaves your computer.

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 latitude — press Enter to accept, or, if
     the guess is wrong, 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 its best guess — accept it or pick another.
   - **Remember:** if the points later look misplaced, the most common cause is that
     latitude and longitude are swapped.

4. **Which column is your grouping variable?**
   - Choose the column that splits your data into two groups — *case* / *control*,
     *affected* / *not affected*, *male* / *female*, *dead* / *alive*, *positive* /
     *negative*, and so on. The map uses the **actual values from your data** as the group
     names automatically — you don't have to type anything.
   - If you don't want any split, choose the first option: *No grouping — show all rows
     the same*.

5. **Which value is the main group?**
   - AdarvMaps lists the values found in the column you chose. Tell it which one is the
     **main group** (it's the highlighted / clustered group; for example, if you coded
     `1 = Case, 0 = Control`, choose `1`).
   - Every other value becomes the other group, shown with its own name.

### Step 4 — Get your map
- Your map appears right below the cell and is saved as a file called `adarvmaps.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 **Spot Map** and **Dot Density**, show one
  group or both, change colours and resize the dots, toggle **place-name labels**, and save
  the map as a **PNG** or **PDF**.

---

## Guide for developers

### Install
```bash
pip install adarvmaps
```
Python 3.9+.

### Usage
```python
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:
```bash
adarvmaps my_data.csv -o 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` | "Case" / "Control" | Names for the two groups, e.g. "Male" / "Female" |
| `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](https://github.com/ADARV-Epi-hub/adarvmaps/blob/main/DOCUMENTATION.md)

> 🔒 **Privacy:** running AdarvMaps locally keeps your data on your machine — nothing is
> uploaded. Google Colab is convenient but runs on Google's cloud, so use it only for
> de-identified or demo data.

---

## 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, an **outcome**:

| 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 |
| **Outcome** (optional) | `outcome`, `status`, `case_control`, `case` | A column with values like `case` / `control` |

**Example:**
```csv
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, and Deepana R.

## License

MIT © ADARV
