spotmap 0.1.0__py3-none-any.whl

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/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/exceptions.py

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

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

spotmap/loader.py

@@ -0,0 +1,156 @@
+"""Smart CSV loading with automatic latitude/longitude and outcome column detection."""
+
+import re
+
+import numpy as np
+import pandas as pd
+
+from .exceptions import ColumnNotFoundError
+
+_FLOAT_PATTERN = re.compile(r"^-?\d+(\.\d+)?$")
+_PAIR_PATTERN = re.compile(
+    r"^[\[\(]?\s*(-?\d+(\.\d+)?)\s*,\s*(-?\d+(\.\d+)?)\s*[\]\)]?$"
+)
+
+_LAT_NAMES = {"lat", "latitude", "y", "northing"}
+_LON_NAMES = {"lon", "long", "longitude", "lng", "x", "easting"}
+_OUTCOME_CANDIDATES = ["outcome", "case_control", "status", "class", "target", "casecontrol"]
+_CASE_VALUES = {"case", "cases", "1", "yes", "true", "positive", "present"}
+
+
+def _sample(df: pd.DataFrame, col: str, n: int = 5) -> list:
+    return df[col].dropna().astype(str).str.strip().head(n).tolist()
+
+
+def _is_float_col(df: pd.DataFrame, col: str) -> bool:
+    samples = _sample(df, col)
+    return bool(samples) and all(_FLOAT_PATTERN.match(x) for x in samples)
+
+
+def _is_pair_col(df: pd.DataFrame, col: str) -> bool:
+    samples = _sample(df, col)
+    return bool(samples) and all(_PAIR_PATTERN.match(x) for x in samples)
+
+
+def _detect_from_combined(df: pd.DataFrame, col: str):
+    """Split a 'lat,lon' or 'lon,lat' combined column; returns (lat_series, lon_series)."""
+    split = (
+        df[col]
+        .astype(str)
+        .str.replace(r"[\[\]()]", "", regex=True)
+        .str.split(",", expand=True)
+    )
+    v1 = pd.to_numeric(split[0].str.strip(), errors="coerce")
+    v2 = pd.to_numeric(split[1].str.strip(), errors="coerce")
+
+    max1, max2 = v1.abs().max(), v2.abs().max()
+
+    if max1 > 90 and max2 <= 90:
+        # first > 90 → must be longitude
+        return v2, v1
+    if max2 > 90 and max1 <= 90:
+        return v1, v2
+    # ambiguous: larger absolute value is longitude
+    lon = np.where(v1.abs() > v2.abs(), v1, v2)
+    lat = np.where(v1.abs() > v2.abs(), v2, v1)
+    return pd.Series(lat, index=df.index), pd.Series(lon, index=df.index)
+
+
+def detect_lat_lon(df: pd.DataFrame, lat_col: str = None, lon_col: str = None):
+    """Return (lat_col_name, lon_col_name) after detection or validation."""
+    cols = list(df.columns)
+
+    # User-supplied — validate they exist
+    if lat_col and lon_col:
+        missing = [c for c in (lat_col, lon_col) if c not in cols]
+        if missing:
+            raise ColumnNotFoundError(f"Columns not found in CSV: {missing}")
+        return lat_col, lon_col
+
+    # Combined column?
+    for col in cols:
+        if _is_pair_col(df, col):
+            lat_s, lon_s = _detect_from_combined(df, col)
+            df["_auto_lat"] = lat_s
+            df["_auto_lon"] = lon_s
+            return "_auto_lat", "_auto_lon"
+
+    # Separate numeric columns
+    numeric_cols = [c for c in cols if _is_float_col(df, c)]
+    found_lat, found_lon = None, None
+
+    for c in numeric_cols:
+        c_lower = c.lower()
+        if any(name in c_lower for name in _LAT_NAMES):
+            found_lat = c
+        if any(name in c_lower for name in _LON_NAMES):
+            found_lon = c
+
+    if found_lat and found_lon:
+        return found_lat, found_lon
+
+    if len(numeric_cols) == 2:
+        return numeric_cols[0], numeric_cols[1]
+
+    raise ColumnNotFoundError(
+        f"Could not auto-detect lat/lon columns. Available columns: {cols}. "
+        "Pass lat_col and lon_col explicitly."
+    )
+
+
+def detect_outcome(df: pd.DataFrame, outcome_col: str = None, case_value: str = None):
+    """Return (outcome_col, case_value) after detection or validation."""
+    cols = list(df.columns)
+
+    if outcome_col and outcome_col not in cols:
+        raise ColumnNotFoundError(
+            f"outcome_col '{outcome_col}' not found. Available: {cols}"
+        )
+
+    if outcome_col is None:
+        for cand in _OUTCOME_CANDIDATES:
+            matches = [c for c in cols if cand in c.lower()]
+            if matches:
+                outcome_col = matches[0]
+                break
+
+    if outcome_col is None:
+        raise ColumnNotFoundError(
+            f"Could not find outcome column. Available columns: {cols}. "
+            "Pass outcome_col explicitly."
+        )
+
+    norm = df[outcome_col].astype(str).str.strip().str.lower().replace({"nan": np.nan})
+    values = norm.dropna().unique()
+
+    if case_value is None:
+        case_value = next((v for v in values if v in _CASE_VALUES), values[0] if len(values) else None)
+
+    if case_value is None:
+        raise ColumnNotFoundError(f"No values found in outcome column '{outcome_col}'.")
+
+    return outcome_col, str(case_value)
+
+
+def load_csv(
+    path: str,
+    lat_col: str = None,
+    lon_col: str = None,
+    outcome_col: str = None,
+    case_value: str = None,
+) -> tuple:
+    """Load and prepare the points CSV.
+
+    Returns:
+        (df, lat_col, lon_col, outcome_col, case_value)
+    """
+    df = pd.read_csv(path)
+    lat_col, lon_col = detect_lat_lon(df, lat_col, lon_col)
+
+    outcome_col, case_value = detect_outcome(df, outcome_col, case_value)
+
+    df["_outcome_norm"] = (
+        df[outcome_col].astype(str).str.strip().str.lower().replace({"nan": np.nan})
+    )
+
+    return df, lat_col, lon_col, outcome_col, case_value

spotmap/map_builder.py

@@ -0,0 +1,196 @@
+"""Main SpotMap class — orchestrates loading, spatial join, and map building."""
+
+import folium
+
+from .exceptions import NoCasePointsError
+from .layers import add_boundary_layers, add_marker_layers
+from .loader import load_csv
+from .sidebar import build_sidebar_html
+from .spatial import (
+    build_india_outline,
+    crop_geodataframe,
+    determine_mode,
+    load_boundaries,
+    spatial_join,
+)
+
+_DEFAULT_CLUSTER_COLOR = "#E85252"
+_DEFAULT_CASE_COLOR = "#D55757"
+_DEFAULT_CONTROL_COLOR = "#7676E7"
+
+
+class SpotMap:
+    """Build an interactive epidemiological spot map for India.
+
+    Parameters
+    ----------
+    csv_path:
+        Path to the CSV file containing point data.
+    state_shp:
+        Optional path to a custom state boundary file (shapefile / GeoPackage /
+        FlatGeobuf).  Defaults to the bundled India state boundaries.
+    district_shp:
+        Optional path to a custom district boundary file.  Defaults to the
+        bundled India district boundaries.
+    lat_col:
+        Column name for latitude.  Auto-detected when omitted.
+    lon_col:
+        Column name for longitude.  Auto-detected when omitted.
+    outcome_col:
+        Column name for the case/control outcome.  Auto-detected when omitted.
+    case_value:
+        Value in *outcome_col* that represents a **case**.  Auto-detected when
+        omitted.
+    count_cutoff:
+        If the number of affected districts is ≤ this value, the map zooms to
+        district level; otherwise to state or national level.
+    margin_deg:
+        Padding (degrees) added around the data bounding box when cropping
+        boundary layers.
+    cluster_color:
+        Hex colour for the dot-density cluster bubbles.
+    case_color:
+        Hex colour for case pins in spot-map mode.
+    control_color:
+        Hex colour for control pins in spot-map mode.
+    """
+
+    def __init__(
+        self,
+        csv_path: str,
+        *,
+        state_shp: str = None,
+        district_shp: str = None,
+        lat_col: str = None,
+        lon_col: str = None,
+        outcome_col: str = None,
+        case_value: str = None,
+        count_cutoff: int = 2,
+        margin_deg: float = 1.0,
+        cluster_color: str = _DEFAULT_CLUSTER_COLOR,
+        case_color: str = _DEFAULT_CASE_COLOR,
+        control_color: str = _DEFAULT_CONTROL_COLOR,
+    ):
+        self.csv_path = csv_path
+        self.state_shp = state_shp
+        self.district_shp = district_shp
+        self.lat_col = lat_col
+        self.lon_col = lon_col
+        self.outcome_col = outcome_col
+        self.case_value = case_value
+        self.count_cutoff = count_cutoff
+        self.margin_deg = margin_deg
+        self.cluster_color = cluster_color
+        self.case_color = case_color
+        self.control_color = control_color
+
+        self._map: folium.Map = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def build(self) -> "SpotMap":
+        """Run the full pipeline and store the Folium map internally.
+
+        Returns *self* so calls can be chained: ``SpotMap(...).build().save(...)``.
+        """
+        # 1. Load CSV
+        df, lat_col, lon_col, outcome_col, case_value = load_csv(
+            self.csv_path,
+            lat_col=self.lat_col,
+            lon_col=self.lon_col,
+            outcome_col=self.outcome_col,
+            case_value=self.case_value,
+        )
+
+        # 2. Load boundaries
+        states, districts, state_name_col, district_name_col = load_boundaries(
+            state_shp=self.state_shp,
+            district_shp=self.district_shp,
+        )
+
+        # 3. Spatial join
+        points_joined = spatial_join(
+            df, lat_col, lon_col, states, districts, state_name_col, district_name_col
+        )
+
+        # 4. Split cases / controls
+        mask = points_joined["_outcome_norm"] == case_value
+        points_cases = points_joined[mask].copy()
+        points_controls = points_joined[~mask].copy()
+
+        if points_cases.empty:
+            raise NoCasePointsError(
+                f"No case points found with outcome value '{case_value}'."
+            )
+
+        # 5. Determine mode + crop boundaries
+        mode, affected_dist_names, unique_state_names, bounds = determine_mode(
+            points_cases, district_name_col, state_name_col, self.count_cutoff
+        )
+
+        india_outline = build_india_outline(states)
+        affected_states = states[states[state_name_col].isin(unique_state_names)].copy()
+        affected_districts = districts[
+            districts[district_name_col].isin(affected_dist_names)
+        ].copy()
+
+        india_sub = crop_geodataframe(india_outline, bounds, self.margin_deg)
+        states_sub = crop_geodataframe(affected_states, bounds, self.margin_deg)
+        districts_sub = crop_geodataframe(affected_districts, bounds, self.margin_deg)
+
+        # 6. Init map
+        zoom = {"india": 4, "states": 5, "districts": 7}[mode]
+        m = folium.Map(
+            location=[points_cases.geometry.y.mean(), points_cases.geometry.x.mean()],
+            zoom_start=zoom,
+            tiles="CartoDB positron",
+        )
+
+        # 7. Boundary layers
+        add_boundary_layers(m, india_sub, states_sub, districts_sub)
+
+        # 8. Marker layers
+        cluster, pins_cases, pins_controls = add_marker_layers(
+            m,
+            points_cases,
+            points_controls,
+            state_name_col,
+            district_name_col,
+            cluster_color=self.cluster_color,
+            case_color=self.case_color,
+            control_color=self.control_color,
+        )
+
+        # 9. Sidebar
+        sidebar_html = build_sidebar_html(
+            map_id=m.get_name(),
+            dots_name=cluster.get_name(),
+            pins_cases_name=pins_cases.get_name(),
+            pins_controls_name=pins_controls.get_name(),
+            mode=mode,
+            n_cases=len(points_cases),
+            n_controls=len(points_controls),
+            cluster_color=self.cluster_color,
+            case_color=self.case_color,
+            control_color=self.control_color,
+        )
+        m.get_root().html.add_child(folium.Element(sidebar_html))
+
+        self._map = m
+        return self
+
+    def save(self, output_path: str) -> "SpotMap":
+        """Save the built map to an HTML file."""
+        if self._map is None:
+            raise RuntimeError("Call .build() before .save().")
+        self._map.save(output_path)
+        return self
+
+    @property
+    def map(self) -> folium.Map:
+        """The underlying Folium map object (after build)."""
+        if self._map is None:
+            raise RuntimeError("Call .build() first.")
+        return self._map

spotmap/sidebar.py

@@ -0,0 +1,360 @@
+"""Sidebar HTML/JS/CSS generation."""
+
+
+def build_sidebar_html(
+    map_id: str,
+    dots_name: str,
+    pins_cases_name: str,
+    pins_controls_name: str,
+    mode: str,
+    n_cases: int,
+    n_controls: int,
+    cluster_color: str,
+    case_color: str,
+    control_color: str,
+) -> str:
+    return f"""
+<style>
+#sidebar-toggle-btn {{
+    position: fixed;
+    top: 10px;
+    right: 10px;
+    z-index: 10000;
+    width: 38px;
+    height: 38px;
+    background: white;
+    border-radius: 4px;
+    box-shadow: 0 1px 4px rgba(0,0,0,0.4);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    font-size: 20px;
+    user-select: none;
+}}
+#sidebar-toggle-btn span {{
+    display: block;
+    width: 20px;
+    height: 2px;
+    background: #333;
+    margin: 3px 0;
+}}
+#sidebar-toggle-btn:hover {{ background: #f4f4f4; }}
+
+#map-sidebar {{
+    position: fixed;
+    top: 10px;
+    right: 10px;
+    bottom: 10px;
+    width: 260px;
+    z-index: 9999;
+    background: white;
+    padding: 10px 12px;
+    border-radius: 6px;
+    box-shadow: 0 1px 4px rgba(0,0,0,0.4);
+    font-size: 13px;
+    overflow-y: auto;
+    transform: translateX(110%);
+    transition: transform 0.25s ease-out;
+    font-family: sans-serif;
+}}
+#map-sidebar.open {{ transform: translateX(0); }}
+#map-sidebar h4 {{
+    margin: 8px 0 6px 0;
+    font-size: 14px;
+    border-bottom: 1px solid #ddd;
+    padding-bottom: 3px;
+    color: #333;
+}}
+#map-sidebar label {{ display: block; margin: 4px 0; cursor: pointer; }}
+#map-sidebar .sidebar-section {{ margin-bottom: 12px; }}
+#map-sidebar .sidebar-footer {{
+    margin-top: 12px;
+    font-size: 11px;
+    color: #555;
+    border-top: 1px solid #eee;
+    padding-top: 8px;
+}}
+#map-sidebar a.download-link {{
+    display: block;
+    margin: 4px 0;
+    color: #0066cc;
+    text-decoration: underline;
+    cursor: pointer;
+    font-weight: 600;
+}}
+#map-sidebar a.download-link:hover {{ color: #004a99; }}
+
+#map-legend {{
+    position: absolute;
+    top: 20px;
+    left: 60px;
+    z-index: 1000;
+    background: rgba(255,255,255,0.9);
+    padding: 8px 10px;
+    border-radius: 4px;
+    box-shadow: 0 1px 4px rgba(0,0,0,0.3);
+    font-size: 12px;
+    font-family: sans-serif;
+    min-width: 100px;
+    border: 1px solid #ccc;
+    display: none;
+}}
+#map-legend h4 {{
+    margin: 0 0 6px 0;
+    font-size: 13px;
+    border-bottom: 1px solid #ccc;
+    padding-bottom: 2px;
+    text-align: center;
+}}
+.legend-item {{ display: flex; align-items: center; margin-bottom: 4px; }}
+.legend-icon {{
+    width: 12px;
+    height: 12px;
+    border-radius: 50%;
+    margin-right: 8px;
+    border: 1px solid rgba(0,0,0,0.2);
+    display: inline-block;
+}}
+
+@media print {{
+    #map-sidebar, #sidebar-toggle-btn {{ display: none !important; }}
+    #map-legend {{ display: block !important; position: absolute; top: 10px; left: 10px; }}
+    .leaflet-control-zoom {{ display: none !important; }}
+}}
+</style>
+
+<div id="sidebar-toggle-btn" title="Map Options">
+  <div><span></span><span></span><span></span></div>
+</div>
+
+<div id="map-legend">
+    <h4>Legend</h4>
+    <div class="legend-item" id="legend-case-item">
+        <span class="legend-icon" id="legend-icon-case" style="background-color:{case_color};"></span>
+        <span>Case</span>
+    </div>
+    <div class="legend-item" id="legend-control-item" style="display:none;">
+        <span class="legend-icon" id="legend-icon-control" style="background-color:{control_color};"></span>
+        <span>Control</span>
+    </div>
+</div>
+
+<div id="map-sidebar">
+  <div class="sidebar-section">
+    <h4>Map Mode</h4>
+    <label><input type="radio" name="markerMode" value="dots" checked> Dot Density (Cases)</label>
+    <label><input type="radio" name="markerMode" value="pins"> Spot Map (Pins)</label>
+  </div>
+
+  <div class="sidebar-section">
+    <h4>Spot Map Filter</h4>
+    <label><input type="radio" name="spotFilterMode" value="cases" checked> Cases Only</label>
+    <label><input type="radio" name="spotFilterMode" value="both"> Cases &amp; Controls</label>
+  </div>
+
+  <div class="sidebar-section">
+    <h4>Cluster Color (Cases)</h4>
+    <label><input type="radio" name="colorMode" value="red"> Red</label>
+    <label><input type="radio" name="colorMode" value="blue"> Blue</label>
+    <label><input type="radio" name="colorMode" value="green"> Green</label>
+    <label>
+      <input type="radio" name="colorMode" value="custom" checked> Custom
+      <input type="color" id="clusterCustomColor" value="{cluster_color}"
+             style="margin-left:6px;vertical-align:middle;width:40px;height:20px;border:none;padding:0;">
+    </label>
+  </div>
+
+  <div class="sidebar-section">
+    <h4>Spot Map Colors</h4>
+    <div style="margin-bottom:6px;">
+      <b>Cases:</b><br>
+      <input type="color" id="caseColorPicker" value="{case_color}"
+             style="vertical-align:middle;width:40px;height:20px;border:none;padding:0;">
+      <button type="button" id="caseApply" style="font-size:11px;margin-left:4px;">Apply</button>
+    </div>
+    <div>
+      <b>Controls:</b><br>
+      <input type="color" id="controlColorPicker" value="{control_color}"
+             style="vertical-align:middle;width:40px;height:20px;border:none;padding:0;">
+      <button type="button" id="controlApply" style="font-size:11px;margin-left:4px;">Apply</button>
+    </div>
+  </div>
+
+  <div class="sidebar-section">
+    <h4>Pin Size</h4>
+    <input type="range" id="pinSizeSlider" min="0.5" max="2.0" step="0.25" value="1.0" style="width:100%;">
+  </div>
+
+  <div class="sidebar-section">
+    <h4>Export</h4>
+    <a id="downloadPrintLink" class="download-link">Print / Save PDF</a>
+    <a id="downloadPngLink" class="download-link">Download PNG</a>
+  </div>
+
+  <div class="sidebar-footer">
+    <div><b>Mode:</b> {mode}</div>
+    <div><b>Cases:</b> {n_cases}</div>
+    <div><b>Controls:</b> {n_controls}</div>
+  </div>
+</div>
+
+<script src="https://unpkg.com/leaflet-simple-map-screenshoter"></script>
+<script>
+window.addEventListener('load', function() {{
+  var mapObj            = {map_id};
+  var dotsLayer         = {dots_name};
+  var pinsCasesLayer    = {pins_cases_name};
+  var pinsControlsLayer = {pins_controls_name};
+
+  // Move legend inside map container so screenshoter captures it
+  var legendDiv = document.getElementById('map-legend');
+  mapObj.getContainer().appendChild(legendDiv);
+
+  var simpleMapScreenshoter = L.simpleMapScreenshoter({{
+      hidden: true,
+      mimeType: 'image/png'
+  }}).addTo(mapObj);
+
+  var sidebar = document.getElementById('map-sidebar');
+  var toggleBtn = document.getElementById('sidebar-toggle-btn');
+  var sidebarOpen = false;
+
+  toggleBtn.addEventListener('click', function() {{
+    sidebarOpen = !sidebarOpen;
+    sidebar.classList.toggle('open', sidebarOpen);
+  }});
+
+  window.caseColor    = '{case_color}';
+  window.controlColor = '{control_color}';
+  window.clusterBaseColor = '{cluster_color}';
+  window.pinScale = 1.0;
+
+  function updateLegend() {{
+    var legendBox = document.getElementById('map-legend');
+    var isPins = document.querySelector('input[name="markerMode"]:checked').value === 'pins';
+    legendBox.style.display = isPins ? 'block' : 'none';
+    if (!isPins) return;
+    document.getElementById('legend-icon-case').style.backgroundColor = window.caseColor;
+    document.getElementById('legend-icon-control').style.backgroundColor = window.controlColor;
+    var isBoth = document.querySelector('input[name="spotFilterMode"]:checked').value === 'both';
+    document.getElementById('legend-control-item').style.display = isBoth ? 'flex' : 'none';
+  }}
+
+  function makePinIcon(colorHex) {{
+    var scale = window.pinScale || 1.0;
+    var baseW = 18, baseH = 24;
+    var html =
+      '<div style="position:relative;width:'+baseW+'px;height:'+baseH+'px;transform:scale('+scale+');transform-origin:50% 100%;">' +
+        '<div style="position:absolute;left:3px;top:6px;width:12px;height:12px;border-radius:50% 50% 50% 0;background:'+colorHex+';transform:rotate(-45deg);box-shadow:0 0 2px rgba(0,0,0,0.5);"></div>' +
+        '<div style="position:absolute;left:6.5px;top:9.5px;width:5px;height:5px;border-radius:50%;background:white;opacity:0.9;"></div>' +
+      '</div>';
+    return new L.DivIcon({{ html: html, className: '', iconSize: [baseW, baseH], iconAnchor: [baseW/2, baseH] }});
+  }}
+
+  function redrawPins() {{
+    if (pinsCasesLayer) {{
+      pinsCasesLayer.eachLayer(function(marker) {{
+        if (marker.setIcon) marker.setIcon(makePinIcon(window.caseColor));
+      }});
+    }}
+    if (pinsControlsLayer) {{
+      pinsControlsLayer.eachLayer(function(marker) {{
+        if (marker.setIcon) marker.setIcon(makePinIcon(window.controlColor));
+      }});
+    }}
+    updateLegend();
+  }}
+
+  function refreshClusters() {{
+    if (mapObj.hasLayer(dotsLayer)) {{
+      mapObj.removeLayer(dotsLayer);
+      mapObj.addLayer(dotsLayer);
+    }}
+  }}
+
+  function applyLayerLogic() {{
+    var mode = document.querySelector('input[name="markerMode"]:checked').value;
+    var filter = document.querySelector('input[name="spotFilterMode"]:checked').value;
+
+    if (mode === 'dots') {{
+      if (!mapObj.hasLayer(dotsLayer)) mapObj.addLayer(dotsLayer);
+      if (mapObj.hasLayer(pinsCasesLayer)) mapObj.removeLayer(pinsCasesLayer);
+      if (mapObj.hasLayer(pinsControlsLayer)) mapObj.removeLayer(pinsControlsLayer);
+    }} else {{
+      if (mapObj.hasLayer(dotsLayer)) mapObj.removeLayer(dotsLayer);
+      if (!mapObj.hasLayer(pinsCasesLayer)) mapObj.addLayer(pinsCasesLayer);
+      if (filter === 'both') {{
+        if (!mapObj.hasLayer(pinsControlsLayer)) mapObj.addLayer(pinsControlsLayer);
+      }} else {{
+        if (mapObj.hasLayer(pinsControlsLayer)) mapObj.removeLayer(pinsControlsLayer);
+      }}
+    }}
+    updateLegend();
+  }}
+
+  document.querySelectorAll('input[type=radio]').forEach(function(r) {{
+    r.addEventListener('change', applyLayerLogic);
+  }});
+
+  // Cluster color
+  var colorRadios = document.getElementsByName('colorMode');
+  var custClust = document.getElementById('clusterCustomColor');
+
+  function updateClusterColor() {{
+    var val = document.querySelector('input[name="colorMode"]:checked').value;
+    if (val === 'red') window.clusterBaseColor = '#FF0000';
+    else if (val === 'blue') window.clusterBaseColor = '#0000FF';
+    else if (val === 'green') window.clusterBaseColor = '#00AA00';
+    else window.clusterBaseColor = custClust.value;
+    refreshClusters();
+  }}
+
+  for (var i = 0; i < colorRadios.length; i++) colorRadios[i].addEventListener('change', updateClusterColor);
+  if (custClust) custClust.addEventListener('input', function() {{
+    document.querySelector('input[name="colorMode"][value="custom"]').checked = true;
+    updateClusterColor();
+  }});
+
+  // Spot map colors
+  document.getElementById('caseApply').addEventListener('click', function() {{
+    window.caseColor = document.getElementById('caseColorPicker').value;
+    redrawPins();
+  }});
+  document.getElementById('controlApply').addEventListener('click', function() {{
+    window.controlColor = document.getElementById('controlColorPicker').value;
+    redrawPins();
+  }});
+
+  // Pin size
+  document.getElementById('pinSizeSlider').addEventListener('input', function(e) {{
+    window.pinScale = parseFloat(e.target.value);
+    redrawPins();
+  }});
+
+  // Export
+  document.getElementById('downloadPrintLink').addEventListener('click', function() {{ window.print(); }});
+  document.getElementById('downloadPngLink').addEventListener('click', function() {{
+    sidebar.classList.remove('open');
+    sidebarOpen = false;
+    setTimeout(function() {{
+      simpleMapScreenshoter.takeScreen('blob', {{ caption: function() {{ return ''; }} }})
+        .then(function(blob) {{
+          var link = document.createElement('a');
+          link.download = 'map.png';
+          link.href = URL.createObjectURL(blob);
+          link.click();
+        }})
+        .catch(function(e) {{ alert(e); }})
+        .finally(function() {{
+          sidebar.classList.add('open');
+          sidebarOpen = true;
+        }});
+    }}, 500);
+  }});
+
+  applyLayerLogic();
+  redrawPins();
+}});
+</script>
+"""

spotmap/spatial.py

@@ -0,0 +1,151 @@
+"""Boundary loading and spatial-join utilities."""
+
+import os
+from pathlib import Path
+
+import geopandas as gpd
+import numpy as np
+from shapely.geometry import Point
+
+os.environ.setdefault("SHAPE_RESTORE_SHX", "YES")
+
+_DATA_DIR = Path(__file__).parent / "data"
+_STATE_FGB = _DATA_DIR / "state_boundary_lite.fgb"
+_DISTRICT_FGB = _DATA_DIR / "district_boundary_lite.fgb"
+
+_STATE_CANDIDATES = ["STATE", "STATE_UT", "ST_NM", "STATE_NAME", "STNAME", "NAME"]
+_DISTRICT_CANDIDATES = [
+    "DISTRICT", "DIST_NEW", "DISTRICT_N",
+    "DT_NAME", "DIST_ROMAN", "dtname", "NAME",
+]
+
+
+def _find_name_col(gdf: gpd.GeoDataFrame, candidates: list, label: str) -> str:
+    col = next((c for c in candidates if c in gdf.columns), None)
+    if col is None:
+        raise ValueError(
+            f"No {label} name column found. "
+            f"Columns present: {list(gdf.columns)}"
+        )
+    return col
+
+
+def _ensure_wgs84(gdf: gpd.GeoDataFrame) -> gpd.GeoDataFrame:
+    if gdf.crs is None:
+        gdf = gdf.set_crs(epsg=4326)
+    elif gdf.crs.to_epsg() != 4326:
+        gdf = gdf.to_crs(epsg=4326)
+    gdf["geometry"] = gdf["geometry"].buffer(0)
+    return gdf
+
+
+def load_boundaries(state_shp: str = None, district_shp: str = None):
+    """Load state and district boundary GeoDataFrames.
+
+    Uses bundled FlatGeobuf files by default.  Pass custom shapefile/GeoPackage
+    paths to override.
+
+    Returns:
+        (states, districts, state_name_col, district_name_col)
+    """
+    state_path = state_shp or str(_STATE_FGB)
+    district_path = district_shp or str(_DISTRICT_FGB)
+
+    states = _ensure_wgs84(gpd.read_file(state_path))
+    districts = _ensure_wgs84(gpd.read_file(district_path))
+
+    state_name_col = _find_name_col(states, _STATE_CANDIDATES, "state")
+    district_name_col = _find_name_col(districts, _DISTRICT_CANDIDATES, "district")
+
+    return states, districts, state_name_col, district_name_col
+
+
+def build_india_outline(states: gpd.GeoDataFrame) -> gpd.GeoDataFrame:
+    geom = states.unary_union
+    return gpd.GeoDataFrame({"geometry": [geom]}, crs=states.crs)
+
+
+def _get_col_safe(joined: gpd.GeoDataFrame, col: str):
+    shp_col = f"{col}_shp"
+    if shp_col in joined.columns:
+        return joined[shp_col].values
+    if col in joined.columns:
+        return joined[col].values
+    return [None] * len(joined)
+
+
+def spatial_join(
+    df,
+    lat_col: str,
+    lon_col: str,
+    states: gpd.GeoDataFrame,
+    districts: gpd.GeoDataFrame,
+    state_name_col: str,
+    district_name_col: str,
+) -> gpd.GeoDataFrame:
+    """Attach state and district names to each point via spatial join."""
+    geometry = [Point(xy) for xy in zip(df[lon_col], df[lat_col])]
+    points = gpd.GeoDataFrame(df.copy(), geometry=geometry, crs="EPSG:4326")
+
+    joined_district = gpd.sjoin(
+        points,
+        districts[[district_name_col, "geometry"]],
+        how="left",
+        predicate="within",
+        lsuffix="_csv",
+        rsuffix="_shp",
+    ).drop(columns=["index_right"], errors="ignore")
+
+    joined_state = gpd.sjoin(
+        points,
+        states[[state_name_col, "geometry"]],
+        how="left",
+        predicate="within",
+        lsuffix="_csv",
+        rsuffix="_shp",
+    ).drop(columns=["index_right"], errors="ignore")
+
+    result = points.copy()
+    result[district_name_col] = _get_col_safe(joined_district, district_name_col)
+    result[state_name_col] = _get_col_safe(joined_state, state_name_col)
+    return result
+
+
+def determine_mode(
+    points_cases: gpd.GeoDataFrame,
+    district_name_col: str,
+    state_name_col: str,
+    count_cutoff: int = 2,
+):
+    """Determine map mode: 'districts', 'states', or 'india'.
+
+    Returns:
+        (mode, affected_districts, unique_states, bounds_array)
+    """
+    affected_districts = points_cases[district_name_col].dropna().unique()
+    unique_states = points_cases[state_name_col].dropna().unique()
+
+    num_districts = len(affected_districts)
+    num_states = len(unique_states)
+
+    if 0 < num_districts <= count_cutoff:
+        mode = "districts"
+    elif num_states > count_cutoff:
+        mode = "india"
+    else:
+        mode = "states"
+
+    bounds = np.array(points_cases.total_bounds, dtype=float)
+    return mode, affected_districts, unique_states, bounds
+
+
+def crop_geodataframe(
+    gdf: gpd.GeoDataFrame, bounds: np.ndarray, margin: float = 1.0
+) -> gpd.GeoDataFrame:
+    if gdf is None or gdf.empty:
+        return gdf
+    if not np.isfinite(bounds).all():
+        return gdf
+    minx, miny, maxx, maxy = bounds
+    sub = gdf.cx[minx - margin : maxx + margin, miny - margin : maxy + margin]
+    return sub if not sub.empty else gdf

spotmap-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+spotmap/__init__.py,sha256=BlQMFe7VlEKl87-xreRDeHGX0jFsdUqzG22cOKjfQsE,283
+spotmap/cli.py,sha256=_Ah-XNV-ogMhZkURmmEcSx5FB12Yq7bF09FLRGgfEWM,2417
+spotmap/downloader.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spotmap/exceptions.py,sha256=TEfnlO-ku_Tx-g1v2UK5v-bwfeabbsQD_IyKmCEkWqo,142
+spotmap/layers.py,sha256=UqsBEhLfxlCg2wS7UNzYU1MLgJxrP8jkcvXgy9NT2CQ,4640
+spotmap/loader.py,sha256=Q3ZaUv8Fm7wLttKhPc0gzKZ2hFQejsQBc_m0bjR6hbM,5076
+spotmap/map_builder.py,sha256=rDQrt2kuu5cZvObWX6LeUfqlnaH1HnLV1zfFRn-M95Q,6715
+spotmap/sidebar.py,sha256=tHp_HXZCzDUghxxWMC0uUAzkPLNjoWJk_JV85bvEcMw,12094
+spotmap/spatial.py,sha256=2oS1TJD9PMIf-VMvbjuQmg72qWN1JU9Kw4WpULrmpbE,4613
+spotmap/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spotmap/data/district_boundary_lite.fgb,sha256=oorTqdpM0bsWvctho_q_BlL_GZOC4HidV5nKJqw6R9k,3436432
+spotmap/data/state_boundary_lite.fgb,sha256=ATPx4_pgJornLF55TyCuNaGpnaFW4xE529w3CdzrsoQ,398000
+spotmap-0.1.0.dist-info/METADATA,sha256=4K79gT7FQKfutiQoE5JfAKuEI-l3VRKRGbaGDcLke3w,4782
+spotmap-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+spotmap-0.1.0.dist-info/entry_points.txt,sha256=EA3N1pqdmutcqtjoGKg4gCtzzLtb8zB3-3SJEsVSBiY,45
+spotmap-0.1.0.dist-info/licenses/LICENSE,sha256=s3GroUjUSdtFQyA4mGVDAva2dUkdSa_7FhlKCFULGhk,1072
+spotmap-0.1.0.dist-info/RECORD,,

spotmap-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

spotmap-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spotmap = spotmap.cli:main

spotmap-0.1.0.dist-info/licenses/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.