spotmap 0.1.0__tar.gz

spotmap-0.1.0/.gitignore

@@ -0,0 +1 @@
+.claude/ 

spotmap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

spotmap-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: spotmap
+Version: 0.1.0
+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: 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

spotmap-0.1.0/README.md

@@ -0,0 +1,108 @@
+# 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

spotmap-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spotmap"
+version = "0.1.0"
+description = "Interactive epidemiological spot maps for India"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+authors = [
+  { name = "Tharun Mallesan", email = "tharunmallesan@gmail.com" }
+]
+keywords = ["epidemiology", "spot map", "india", "geospatial", "folium", "case-control"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: GIS",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+  "Intended Audience :: Science/Research",
+]
+dependencies = [
+  "folium>=0.14",
+  "geopandas>=0.13",
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "shapely>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/TharunMallesan/spotmap"
+Repository = "https://github.com/TharunMallesan/spotmap"
+"Bug Tracker" = "https://github.com/TharunMallesan/spotmap/issues"
+
+[project.scripts]
+spotmap = "spotmap.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["spotmap"]
+
+[tool.hatch.build.targets.sdist]
+include = ["spotmap/", "README.md", "LICENSE", "pyproject.toml"]

spotmap-0.1.0/spotmap/__init__.py

@@ -0,0 +1,7 @@
+"""spotmap — Interactive epidemiological spot maps for India."""
+
+from .exceptions import ColumnNotFoundError, NoCasePointsError, SpotMapError
+from .map_builder import SpotMap
+
+__version__ = "0.1.0"
+__all__ = ["SpotMap", "SpotMapError", "ColumnNotFoundError", "NoCasePointsError"]

spotmap-0.1.0/spotmap/cli.py

@@ -0,0 +1,75 @@
+"""Command-line interface for spotmap."""
+
+import argparse
+import sys
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="spotmap",
+        description="Generate an interactive epidemiological spot map for India.",
+    )
+    p.add_argument("csv", help="Path to the input CSV file with point data.")
+    p.add_argument(
+        "-o", "--output",
+        default="spotmap_output.html",
+        help="Output HTML file path (default: spotmap_output.html).",
+    )
+    p.add_argument("--state-shp", default=None, help="Custom state boundary file.")
+    p.add_argument("--district-shp", default=None, help="Custom district boundary file.")
+    p.add_argument("--lat-col", default=None, help="Latitude column name.")
+    p.add_argument("--lon-col", default=None, help="Longitude column name.")
+    p.add_argument("--outcome-col", default=None, help="Outcome column name.")
+    p.add_argument("--case-value", default=None, help="Value that represents a case.")
+    p.add_argument(
+        "--count-cutoff",
+        type=int,
+        default=2,
+        help="District count threshold for mode selection (default: 2).",
+    )
+    p.add_argument(
+        "--cluster-color",
+        default="#E85252",
+        help="Hex colour for dot-density clusters (default: #E85252).",
+    )
+    p.add_argument(
+        "--case-color",
+        default="#D55757",
+        help="Hex colour for case pins (default: #D55757).",
+    )
+    p.add_argument(
+        "--control-color",
+        default="#7676E7",
+        help="Hex colour for control pins (default: #7676E7).",
+    )
+    return p
+
+
+def main(argv=None) -> None:
+    from .map_builder import SpotMap
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        SpotMap(
+            args.csv,
+            state_shp=args.state_shp,
+            district_shp=args.district_shp,
+            lat_col=args.lat_col,
+            lon_col=args.lon_col,
+            outcome_col=args.outcome_col,
+            case_value=args.case_value,
+            count_cutoff=args.count_cutoff,
+            cluster_color=args.cluster_color,
+            case_color=args.case_color,
+            control_color=args.control_color,
+        ).build().save(args.output)
+        print(f"Map saved to: {args.output}")
+    except Exception as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

spotmap-0.1.0/spotmap/exceptions.py

@@ -0,0 +1,10 @@
+class SpotMapError(Exception):
+    pass
+
+
+class ColumnNotFoundError(SpotMapError):
+    pass
+
+
+class NoCasePointsError(SpotMapError):
+    pass

spotmap-0.1.0/spotmap/layers.py

@@ -0,0 +1,153 @@
+"""Folium layer builders for dot-density clusters and spot-map pins."""
+
+import folium
+import geopandas as gpd
+from folium.plugins import MarkerCluster
+
+
+def _cluster_icon_fn(cluster_color: str, total_cases: int) -> str:
+    return f"""
+function(cluster) {{
+    var count = cluster.getChildCount();
+    var total = {total_cases};
+
+    var frac = count / total;
+    if (!isFinite(frac) || frac < 0) frac = 0;
+    if (frac > 1) frac = 1;
+
+    var baseHex = window.clusterBaseColor || '{cluster_color}';
+
+    function hexToRgb(hex) {{
+        if (!hex) return {{r: 255, g: 0, b: 0}};
+        var c = hex.replace('#','');
+        if (c.length === 3) c = c[0]+c[0]+c[1]+c[1]+c[2]+c[2];
+        var num = parseInt(c, 16);
+        return {{r: (num >> 16) & 255, g: (num >> 8) & 255, b: num & 255}};
+    }}
+
+    function mixWithWhite(rgb, t) {{
+        t = Math.max(0, Math.min(1, t));
+        return {{
+            r: Math.round(255*(1-t) + rgb.r*t),
+            g: Math.round(255*(1-t) + rgb.g*t),
+            b: Math.round(255*(1-t) + rgb.b*t)
+        }};
+    }}
+
+    var baseRgb = hexToRgb(baseHex);
+    var t = 0.4 + 0.6 * Math.sqrt(frac);
+    if (!isFinite(t) || t < 0.4) t = 0.4;
+    if (t > 1) t = 1;
+
+    var mixed = mixWithWhite(baseRgb, t);
+    var color = 'rgba('+mixed.r+','+mixed.g+','+mixed.b+',0.95)';
+    var size = 30 + Math.min(25, Math.sqrt(count) * 3);
+
+    return new L.DivIcon({{
+        html: '<div style="background:'+color+
+              '; width:'+size+'px; height:'+size+
+              'px; border-radius:50%; display:flex; align-items:center; justify-content:center; '+
+              'box-shadow:0 0 6px rgba(0,0,0,0.4); font-weight:bold;">'+count+'</div>',
+        className: 'cluster-icon',
+        iconSize: new L.Point(size, size)
+    }});
+}}
+"""
+
+
+def add_boundary_layers(
+    m: folium.Map,
+    india_outline: gpd.GeoDataFrame,
+    affected_states: gpd.GeoDataFrame,
+    affected_districts: gpd.GeoDataFrame,
+) -> None:
+    folium.GeoJson(
+        india_outline,
+        name="India Border",
+        control=False,
+        style_function=lambda x: {
+            "fillOpacity": 0.0,
+            "color": "#000000",
+            "weight": 1,
+            "opacity": 0.5,
+        },
+    ).add_to(m)
+
+    folium.GeoJson(
+        affected_states,
+        name="Affected States",
+        control=False,
+        style_function=lambda x: {
+            "fillOpacity": 0.05,
+            "color": "#4B0082",
+            "weight": 1.5,
+            "opacity": 0.7,
+        },
+    ).add_to(m)
+
+    folium.GeoJson(
+        affected_districts,
+        name="Affected Districts",
+        control=False,
+        style_function=lambda x: {
+            "color": "#000000",
+            "weight": 1,
+            "fillOpacity": 0.01,
+            "opacity": 1.0,
+        },
+    ).add_to(m)
+
+
+def add_marker_layers(
+    m: folium.Map,
+    points_cases: gpd.GeoDataFrame,
+    points_controls: gpd.GeoDataFrame,
+    state_name_col: str,
+    district_name_col: str,
+    cluster_color: str,
+    case_color: str,
+    control_color: str,
+):
+    """Add dot-density cluster and spot-map pin layers.
+
+    Returns:
+        (cluster_layer, pins_cases_layer, pins_controls_layer)
+    """
+    total_cases = len(points_cases) or 1
+
+    cluster = MarkerCluster(
+        name="Dot Density Layer",
+        icon_create_function=_cluster_icon_fn(cluster_color, total_cases),
+        disableClusteringAtZoom=15,
+        spiderfyOnMaxZoom=True,
+        showCoverageOnHover=False,
+        maxClusterRadius=60,
+        singleMarkerMode=True,
+    )
+    m.add_child(cluster)
+
+    pins_cases_layer = folium.FeatureGroup(name="Spot Map - Cases")
+    pins_controls_layer = folium.FeatureGroup(name="Spot Map - Controls")
+    m.add_child(pins_cases_layer)
+    m.add_child(pins_controls_layer)
+
+    for _, row in points_cases.iterrows():
+        lat, lon = row.geometry.y, row.geometry.x
+        popup = (
+            f"<b>Type:</b> Case<br>"
+            f"<b>State:</b> {row.get(state_name_col, '')}<br>"
+            f"<b>District:</b> {row.get(district_name_col, '')}"
+        )
+        folium.Marker(location=[lat, lon], popup=popup).add_to(cluster)
+        folium.Marker(location=[lat, lon], popup=popup).add_to(pins_cases_layer)
+
+    for _, row in points_controls.iterrows():
+        lat, lon = row.geometry.y, row.geometry.x
+        popup = (
+            f"<b>Type:</b> Control<br>"
+            f"<b>State:</b> {row.get(state_name_col, '')}<br>"
+            f"<b>District:</b> {row.get(district_name_col, '')}"
+        )
+        folium.Marker(location=[lat, lon], popup=popup).add_to(pins_controls_layer)
+
+    return cluster, pins_cases_layer, pins_controls_layer