Metadata-Version: 2.4
Name: spotmap
Version: 0.1.9
Summary: Interactive epidemiological spot maps for India
Project-URL: Homepage, https://github.com/TharunMallesan/spotmap
Project-URL: Repository, https://github.com/TharunMallesan/spotmap
Project-URL: Bug Tracker, https://github.com/TharunMallesan/spotmap/issues
Author-email: Tharun Mallesan <tharunmallesan@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Tharun Mallesan
        
        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: 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
Description-Content-Type: text/markdown

# 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

```bash
pip install spotmap
```

---

## Quick start

### Python API

```python
from spotmap import SpotMap

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

### Command line

```bash
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:

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

---

## Python API reference

```python
SpotMap(
    csv_path,                       # required
    state_shp=None,                 # custom state boundary (shapefile/GeoPackage)
    district_shp=None,              # custom district boundary
    lat_col=None,                   # override auto-detection
    lon_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:

```python
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
```

---

## License

MIT © Tharun Mallesan
