adarvmap 0.1.41__py3-none-any.whl

adarvmap/__init__.py

@@ -0,0 +1,61 @@
+"""adarvmap — Interactive epidemiological spot maps for India."""
+
+from .exceptions import ColumnNotFoundError, NoCasePointsError, AdarvMapError
+from .interactive import run_interactive, adarvmap_run
+from .map_builder import AdarvMap
+
+# Short, friendly alias so non-coders can simply do:  import adarvmap; adarvmap.run()
+run = adarvmap_run
+
+__version__ = "0.1.41"
+__all__ = [
+    "AdarvMap",
+    "run",  # friendly alias for adarvmap_run
+    "adarvmap_run",
+    "run_interactive",  # deprecated alias, kept for backward compat
+    "AdarvMapError",
+    "ColumnNotFoundError",
+    "NoCasePointsError",
+]
+
+_BANNER = (
+    "\n"
+    "Interactive AdarvMap for India - created by ADARV\n"
+    "\n"
+    "No code required! To build your map, just run:\n"
+    "\n"
+    "adarvmap.run()\n"
+    "\n"
+    "You'll be asked to choose your data file, then your map appears.\n"
+)
+
+
+def _in_interactive_session() -> bool:
+    """True for a REPL, Jupyter/Colab notebook, or an interactive terminal."""
+    import sys
+
+    if "ipykernel" in sys.modules or "google.colab" in sys.modules:
+        return True
+    if hasattr(sys, "ps1"):  # plain Python REPL
+        return True
+    try:
+        return bool(sys.stdout.isatty())
+    except Exception:  # noqa: BLE001 — detached/!closed streams
+        return False
+
+
+def _show_banner() -> None:
+    """Show the first-run hint for non-coders.
+
+    Written to **stderr**, and only in an interactive session, so that
+    importing adarvmap never pollutes piped or redirected stdout (which
+    would corrupt scripts that emit CSV/JSON).  This mirrors R's
+    ``packageStartupMessage`` behaviour in the sibling adarvmapr package.
+    """
+    import sys
+
+    if _in_interactive_session():
+        print(_BANNER, file=sys.stderr)
+
+
+_show_banner()

adarvmap/cli.py

@@ -0,0 +1,114 @@
+"""Command-line interface for adarvmap."""
+
+import argparse
+import sys
+
+
+_EPILOG = """\
+Examples:
+  adarvmap                            launch the guided wizard (easiest)
+  adarvmap data.csv                   build a map from data.csv
+  adarvmap data.csv -o my_map.html    choose where to save the map
+
+In Python or Google Colab:
+  from adarvmap import adarvmap_run
+  adarvmap_run()
+"""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="adarvmap",
+        description="Generate an interactive epidemiological spot map for India.",
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument(
+        "csv",
+        nargs="?",
+        default=None,
+        help="Path to your data file (CSV/Excel). Omit it to launch the guided wizard.",
+    )
+    p.add_argument(
+        "-o", "--output",
+        default=None,
+        help="Output HTML file path (default: a dated file, e.g. adarvmap_200926.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).",
+    )
+    p.add_argument(
+        "--case-label",
+        default=None,
+        help="Name for the case group on the map, e.g. Male (default: Case).",
+    )
+    p.add_argument(
+        "--control-label",
+        default=None,
+        help="Name for the control group on the map, e.g. Female (default: Control).",
+    )
+    return p
+
+
+def main(argv=None) -> None:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    # No data file given → launch the friendly step-by-step wizard.
+    if args.csv is None:
+        from .interactive import adarvmap_run
+        adarvmap_run(args.output)
+        return
+
+    from .map_builder import AdarvMap
+    from .interactive import _default_output
+
+    output = args.output or _default_output()
+    try:
+        AdarvMap(
+            args.csv,
+            state_shp=args.state_shp,
+            district_shp=args.district_shp,
+            lat_col=args.lat_col,
+            long_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,
+            case_label=args.case_label,
+            control_label=args.control_label,
+        ).build().save(output)
+        print(f"Map saved to: {output}")
+    except Exception as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

adarvmap/exceptions.py

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