wildlocate 0.1.0__tar.gz

wildlocate-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: wildlocate
+Version: 0.1.0
+Requires-Python: >=3.10
+Requires-Dist: geopandas
+Requires-Dist: joblib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: platformdirs
+Requires-Dist: pyproj
+Requires-Dist: PyQt6
+Requires-Dist: PyQt6-WebEngine
+Requires-Dist: rasterio
+Requires-Dist: requests
+Requires-Dist: scikit-learn
+Requires-Dist: shapely

wildlocate-0.1.0/README.md

@@ -0,0 +1,63 @@
+# WildLocate
+
+# Installation From Source
+
+Clone
+
+```git clone https://github.com/cx-57/Wild-Locate```
+
+Create Virtual Environment
+
+```python -m venv .venv```
+
+Install WildLocate (Installs Deps)
+```pip install -e .```
+
+Setup & Run
+
+Download Datasets
+```wildlocate init```
+
+Launch
+```wildlocate```
+
+## Train a species in the desktop app
+
+Open **Manage species → Train a new species**. Enter an exact common or scientific
+name, select **Find species**, and confirm the matched mammal. The app checks local
+environmental datasets and downloads research-grade Massachusetts observations
+from iNaturalist. If environmental data is missing, use **Download environmental
+data**, then check the species again.
+
+After cleaning, at least 25 observations are required to attempt training; their
+spatial distribution and the available background samples can still prevent valid
+five-fold evaluation. Select **Start training** to prepare background locations,
+extract habitat features, compare models and fit the selected model. Downloads
+require internet access. Training runs in a separate process, reports progress and
+can be cancelled.
+
+Completed models appear under **Your models**. Review the observation counts and
+spatial validation results, then select **Enable model** to add the species to the
+analysis dropdown. Validation scores are not probabilities of wildlife presence
+or a guarantee of ecological reliability. Retraining creates a separate model;
+the current model stays enabled until a replacement is explicitly enabled.
+Custom models can be deleted, and bundled models can be re-enabled at any time.
+
+Custom models, training files and the background-observation cache are stored in
+the per-user `wildlocate` application-data directory, not inside the installed
+package. `WILDLOCATE_DATA_DIR` optionally overrides this directory. Completed
+models must include their model, metadata and comparison dataset before they can
+be enabled. The API and desktop dropdown use the same model registry.
+
+This version supports training Massachusetts mammals using the existing habitat
+features. Other regions and animal groups require additional data and modeling work.
+
+## Tests
+
+```powershell
+python -m unittest discover -s tests -v
+```
+
+Tests use isolated storage under `artifacts/test-runs`, mock external downloads,
+train and reload a real model, and exercise the desktop workflow and background
+process cancellation. They do not require environmental downloads.

wildlocate-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=70", "wheel"]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "wildlocate"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "geopandas",
+    "joblib",
+    "numpy",
+    "pandas",
+    "platformdirs",
+    "pyproj",
+    "PyQt6",
+    "PyQt6-WebEngine",
+    "rasterio",
+    "requests",
+    "scikit-learn",
+    "shapely",
+]
+
+[project.scripts]
+wildlocate = "wildlocate.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["wildlocate*"]
+
+[tool.setuptools.package-data]
+"wildlocate" = [
+    "gui/map/index.html",
+    "gui/map/map.css",
+    "gui/map/map.js",
+    "gui/map/vendor/*",
+    "data/processed/models/*.joblib",
+    "data/processed/models/*.json",
+    "data/processed/features/species/*.csv",
+]

wildlocate-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wildlocate-0.1.0/wildlocate/__init__.py

@@ -0,0 +1,3 @@
+"""Wild-Locate: desktop habitat suitability explorer for Massachusetts wildlife."""
+
+__version__ = "0.1.0"

wildlocate-0.1.0/wildlocate/__main__.py

@@ -0,0 +1,3 @@
+from wildlocate.cli import main
+
+main()

wildlocate-0.1.0/wildlocate/cli.py

@@ -0,0 +1,91 @@
+import argparse
+import sys
+from pathlib import Path
+
+
+def cmd_gui(args):
+    from wildlocate.gui.app import main as gui_main
+    gui_main()
+
+
+def cmd_init(args):
+    from wildlocate.core.data.environment import get_user_data_dir
+    data_dir = get_user_data_dir()
+    raw_dir = data_dir / "raw"
+
+    print(f"Wild-Locate: downloading environmental datasets to {data_dir}")
+    print("This may take several minutes.\n")
+
+    from wildlocate.core.data.nlcd.download import download_nlcd
+    nlcd_dir = raw_dir / "nlcd"
+    print("Downloading NLCD land cover and impervious surface...")
+    download_nlcd(nlcd_dir, year=2025, tiles=4)
+    print()
+
+    from wildlocate.core.data.usgs_3dep.download import download_elevation
+    usgs_dir = raw_dir / "usgs_3dep"
+    print("Downloading USGS 3DEP elevation...")
+    download_elevation(
+        bbox=(-73.60, 41.10, -69.80, 42.95),
+        output_path=usgs_dir / "elevation_3dep.tif",
+    )
+    print()
+
+    from wildlocate.core.data.massdep_hydrography.download import download_hydrography
+    hydro_dir = raw_dir / "massdep_hydrography"
+    print("Downloading MassDEP hydrography...")
+    download_hydrography(hydro_dir / "massachusetts_hydrography.zip")
+    print()
+
+    from wildlocate.core.data.massdot_roads.download import download_roads
+    roads_dir = raw_dir / "massdot_roads"
+    print("Downloading MassDOT roads...")
+    download_roads(roads_dir / "massachusetts_roads.zip")
+    print()
+
+    print("All datasets downloaded. Run 'wildlocate' to launch the app.")
+
+
+def cmd_status(args):
+    from wildlocate.core.data.environment import DatasetPaths
+    paths = DatasetPaths()
+    datasets = {
+        "NLCD land cover": paths.nlcd_landcover,
+        "NLCD impervious surface": paths.nlcd_impervious,
+        "USGS 3DEP elevation": paths.usgs_3dep_elevation,
+        "MassDEP hydrography (poly)": paths.massdep_hydrography_poly,
+        "MassDEP hydrography (arc)": paths.massdep_hydrography_arc,
+        "MassDOT roads": paths.massdot_roads,
+    }
+    all_ok = True
+    for name, path in datasets.items():
+        status = "OK" if path.exists() else "MISSING"
+        if not path.exists():
+            all_ok = False
+        print(f"  [{status}] {name}")
+        print(f"         {path}")
+    print()
+    if all_ok:
+        print("All datasets are available.")
+    else:
+        print("Some datasets are missing. Run 'wildlocate init' to download them.")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="wildlocate",
+        description="Wild-Locate habitat explorer for Massachusetts wildlife",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+    subparsers.add_parser("gui", help="Launch the GUI (default)")
+    subparsers.add_parser("init", help="Download required environmental datasets")
+    subparsers.add_parser("status", help="Check dataset availability")
+
+    args = parser.parse_args()
+
+    if args.command in (None, "gui"):
+        cmd_gui(args)
+    elif args.command == "init":
+        cmd_init(args)
+    elif args.command == "status":
+        cmd_status(args)

wildlocate-0.1.0/wildlocate/core/api.py

@@ -0,0 +1,79 @@
+from enum import Enum
+
+from fastapi import Body, FastAPI
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from pydantic import ConfigDict, Field, ValidationError, create_model
+
+from wildlocate.core.registry import available_species
+from wildlocate.core.service import PredictionError, assess_habitat
+
+app = FastAPI(
+    title="Wild-Locate",
+    description="Relative habitat suitability for wildlife. Scores are not probabilities of species presence.",
+    version="1.0.0",
+)
+
+
+PredictionRequest = create_model(
+    "PredictionRequest",
+    __config__=ConfigDict(extra="forbid", str_strip_whitespace=True),
+    species=(str, Field(min_length=1, max_length=100)),
+    latitude=(float, Field(ge=-90, le=90, allow_inf_nan=False, strict=True)),
+    longitude=(float, Field(ge=-180, le=180, allow_inf_nan=False, strict=True)),
+)
+
+SuitabilityCategory = Enum("SuitabilityCategory", {
+    "VERY_LOW": "Very Low", "LOW": "Low", "MODERATE": "Moderate",
+    "HIGH": "High", "VERY_HIGH": "Very High",
+}, type=str)
+
+PredictionResponse = create_model(
+    "PredictionResponse",
+    species=(str, ...),
+    latitude=(float, ...),
+    longitude=(float, ...),
+    score=(float, Field(allow_inf_nan=False)),
+    percentile=(int, Field(ge=0, le=100)),
+    category=(SuitabilityCategory, ...),
+    model=(str, ...),
+    training_observations=(int, ...),
+    features=(dict[str, float], ...),
+)
+
+
+@app.exception_handler(PredictionError)
+async def prediction_error_handler(request, exc):
+    return JSONResponse(status_code=exc.status_code, content={"detail": str(exc), "code": exc.code})
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_error_handler(request, exc):
+    fields = sorted({str(error["loc"][-1]) for error in exc.errors()})
+    return JSONResponse(status_code=422, content={
+        "detail": "Check the request: supply a species, latitude from −90 to 90, and longitude from −180 to 180 as numbers.",
+        "code": "invalid_request", "fields": fields,
+    })
+
+
+@app.get("/species")
+def species():
+    return {"species": list(available_species())}
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+
+@app.post("/predict", response_model=PredictionResponse, openapi_extra={
+    "requestBody": {"content": {"application/json": {"schema": PredictionRequest.model_json_schema()}}},
+})
+def predict(request=Body(...)):
+    try:
+        request = PredictionRequest.model_validate(request)
+    except ValidationError as exc:
+        raise RequestValidationError([
+            {**error, "loc": ("body", *error["loc"])} for error in exc.errors()
+        ]) from exc
+    return assess_habitat(request.species, request.latitude, request.longitude)

wildlocate-0.1.0/wildlocate/core/catalog.py

@@ -0,0 +1,8 @@
+# Bundled models. Runtime species availability comes from core.registry.
+SUPPORTED_SPECIES = (
+    "Bobcat",
+    "Fisher",
+    "North American River Otter",
+    "Red Fox",
+    "Coyote",
+)

wildlocate-0.1.0/wildlocate/core/data/background.py

@@ -0,0 +1,359 @@
+#!/usr/bin/env python3
+
+import argparse
+import math
+import re
+import sys
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import requests
+from pyproj import Transformer
+
+from wildlocate.core.data.inaturalist import resolve_species
+
+API_BASE = "https://api.inaturalist.org/v1"
+MAMMAL_POOL_FILE = Path("data/processed/samples/massachusetts_mammal_pool.csv")
+DEFAULT_MAX_MAMMAL_POOL = 50000
+
+
+def species_slug(species_name):
+    slug = re.sub(r"[^a-z0-9]+", "_", species_name.strip().lower())
+    slug = slug.strip("_")
+    if not slug:
+        raise ValueError("Species name is required.")
+    return slug
+
+
+def api_get(endpoint, params=None):
+    response = requests.get(f"{API_BASE}{endpoint}", params=params, timeout=60)
+    response.raise_for_status()
+    data = response.json()
+    if "error" in data:
+        raise RuntimeError(data["error"])
+    return data
+
+
+def find_place_id(place_name):
+    place_name = place_name.strip()
+    if not place_name:
+        raise ValueError("Place name is required.")
+
+    data = api_get("/places/autocomplete", {"q": place_name, "per_page": 20})
+    results = data.get("results", [])
+    if not results:
+        raise RuntimeError(f"Could not find place: {place_name}")
+    return int(results[0]["id"])
+
+
+def download_mammal_pool(place_name="Massachusetts", progress=None):
+    mammals = resolve_species("Mammalia")
+    place_id = find_place_id(place_name)
+
+    rows = []
+    id_above = 0
+    total_rows = 0
+
+    while total_rows < DEFAULT_MAX_MAMMAL_POOL:
+        params = {
+            "taxon_id": mammals["taxon_id"],
+            "place_id": place_id,
+            "quality_grade": "research",
+            "verifiable": "true",
+            "captive": "false",
+            "per_page": 200,
+            "order_by": "id",
+            "order": "asc",
+            "id_above": id_above,
+        }
+
+        data = api_get("/observations", params)
+        batch = data.get("results", [])
+        if not batch:
+            break
+
+        for obs in batch:
+            geojson = obs.get("geojson") or {}
+            coords = geojson.get("coordinates")
+            if not coords or len(coords) < 2:
+                continue
+
+            longitude, latitude = coords[:2]
+            try:
+                latitude = float(latitude)
+                longitude = float(longitude)
+            except (TypeError, ValueError):
+                continue
+
+            if not (-90 <= latitude <= 90) or not (-180 <= longitude <= 180):
+                continue
+
+            taxon = obs.get("taxon") or {}
+            rows.append(
+                {
+                    "observation_id": obs.get("id"),
+                    "taxon_id": taxon.get("id"),
+                    "taxon_name": taxon.get("scientific_name") or taxon.get("name"),
+                    "common_name": taxon.get("preferred_common_name") or taxon.get("common_name"),
+                    "latitude": latitude,
+                    "longitude": longitude,
+                    "positional_accuracy": obs.get("positional_accuracy"),
+                    "observed_on": obs.get("observed_on"),
+                    "coordinates_obscured": bool(obs.get("obscured", False)),
+                }
+            )
+
+            total_rows += 1
+            if total_rows >= DEFAULT_MAX_MAMMAL_POOL:
+                break
+
+        if len(batch) < params["per_page"]:
+            break
+
+        id_above = batch[-1]["id"]
+        if progress:
+            progress(f"Downloaded {total_rows:,} Massachusetts background observations…")
+
+    if not rows:
+        raise RuntimeError("No usable Massachusetts Mammalia observations were found.")
+
+    df = pd.DataFrame(rows)
+    df["observation_id"] = pd.to_numeric(df["observation_id"], errors="coerce")
+    df["taxon_id"] = pd.to_numeric(df["taxon_id"], errors="coerce")
+    df["positional_accuracy"] = pd.to_numeric(df["positional_accuracy"], errors="coerce")
+
+    return df
+
+
+def load_or_create_mammal_pool(refresh_pool=False, pool_file=None, progress=None):
+    pool_file = Path(pool_file) if pool_file is not None else MAMMAL_POOL_FILE
+    if pool_file.exists() and not refresh_pool:
+        pool_df = pd.read_csv(pool_file)
+        required_columns = {
+            "observation_id", "taxon_id", "taxon_name", "common_name",
+            "latitude", "longitude", "positional_accuracy", "observed_on",
+            "coordinates_obscured",
+        }
+        missing = required_columns.difference(pool_df.columns)
+        if missing:
+            raise ValueError(
+                f"Existing mammal pool at {pool_file} is missing required columns: {sorted(missing)}"
+            )
+        return pool_df
+
+    pool_df = download_mammal_pool(progress=progress)
+    pool_file.parent.mkdir(parents=True, exist_ok=True)
+    pool_df.to_csv(pool_file, index=False)
+    return pool_df
+
+
+def project_to_5070(df):
+    transformer = Transformer.from_crs("EPSG:4326", "EPSG:5070", always_xy=True)
+    x_5070, y_5070 = transformer.transform(df["longitude"].to_numpy(), df["latitude"].to_numpy())
+
+    projected = df.copy()
+    projected["x_5070"] = x_5070
+    projected["y_5070"] = y_5070
+    return projected
+
+
+def filter_mammal_pool(pool_df, target_taxon_id):
+    if pool_df is None or pool_df.empty:
+        return pool_df
+
+    filtered = pool_df.copy()
+
+    filtered = filtered.dropna(subset=["latitude", "longitude"]).copy()
+    filtered["latitude"] = pd.to_numeric(filtered["latitude"], errors="coerce")
+    filtered["longitude"] = pd.to_numeric(filtered["longitude"], errors="coerce")
+    filtered = filtered.dropna(subset=["latitude", "longitude"]).copy()
+
+    filtered["coordinates_obscured"] = (
+        filtered["coordinates_obscured"].fillna(False).astype(str).str.lower() == "true"
+    )
+    filtered = filtered[~filtered["coordinates_obscured"]].copy()
+
+    filtered["positional_accuracy"] = pd.to_numeric(filtered["positional_accuracy"], errors="coerce")
+    filtered = filtered[
+        filtered["positional_accuracy"].isna() | (filtered["positional_accuracy"] <= 250)
+    ].copy()
+
+    filtered = filtered.drop_duplicates(subset=["observation_id"]).copy()
+    filtered = filtered.drop_duplicates(subset=["latitude", "longitude"]).copy()
+
+    if target_taxon_id is not None:
+        filtered = filtered[filtered["taxon_id"] != target_taxon_id].copy()
+
+    return filtered
+
+
+def compute_min_distance_to_presence(candidate_x, candidate_y, presence_x, presence_y):
+    distances = np.full(candidate_x.shape[0], np.inf, dtype=float)
+
+    for idx, (cx, cy) in enumerate(zip(candidate_x, candidate_y)):
+        diff_x = presence_x - cx
+        diff_y = presence_y - cy
+        distances[idx] = np.sqrt(np.min(diff_x**2 + diff_y**2))
+
+    return distances
+
+
+def spatial_thin(df, thinning_distance_m, random_state):
+    if df.empty:
+        return df
+
+    projected = project_to_5070(df)
+    projected["grid_x"] = np.floor(projected["x_5070"] / thinning_distance_m).astype(int)
+    projected["grid_y"] = np.floor(projected["y_5070"] / thinning_distance_m).astype(int)
+
+    rng = np.random.default_rng(random_state)
+    order = rng.permutation(len(projected))
+    kept = []
+    seen_cells = set()
+
+    for idx in order:
+        row = projected.iloc[idx]
+        cell = (int(row["grid_x"]), int(row["grid_y"]))
+        if cell in seen_cells:
+            continue
+        seen_cells.add(cell)
+        kept.append(idx)
+
+    return projected.iloc[kept].reset_index(drop=True)
+
+
+def generate_background(
+    species_name,
+    background_ratio=3.0,
+    exclusion_distance_m=1000,
+    thinning_distance_m=500,
+    random_state=42,
+    *, samples_dir="data/processed/samples", pool_file=None, taxon_id=None, progress=None,
+):
+    if background_ratio <= 0:
+        raise ValueError("background_ratio must be greater than 0.")
+    if exclusion_distance_m < 0:
+        raise ValueError("exclusion_distance_m must be non-negative.")
+    if thinning_distance_m <= 0:
+        raise ValueError("thinning_distance_m must be greater than 0.")
+
+    target_taxon_id = int(taxon_id if taxon_id is not None else resolve_species(species_name)["taxon_id"])
+
+    species_slug_value = species_slug(species_name)
+    samples_dir = Path(samples_dir)
+    presence_file = samples_dir / f"{species_slug_value}_occurrences.csv"
+    if not presence_file.exists():
+        raise FileNotFoundError(
+            f"Could not find cleaned presence file at {presence_file}. Run the Phase 3 species download first."
+        )
+
+    presence_df = pd.read_csv(presence_file)
+    presence_df = presence_df.dropna(subset=["latitude", "longitude"]).copy()
+    presence_df["latitude"] = pd.to_numeric(presence_df["latitude"], errors="coerce")
+    presence_df["longitude"] = pd.to_numeric(presence_df["longitude"], errors="coerce")
+    presence_df = presence_df.dropna(subset=["latitude", "longitude"]).copy()
+
+    if presence_df.empty:
+        raise RuntimeError(f"No usable presence points found in {presence_file}.")
+
+    pool_df = load_or_create_mammal_pool(pool_file=pool_file, progress=progress)
+    candidate_df = filter_mammal_pool(pool_df, target_taxon_id)
+
+    if candidate_df.empty:
+        raise RuntimeError(
+            f"No usable mammal-pool candidates remain after quality filtering for {species_name}."
+        )
+
+    projected_presence = project_to_5070(presence_df)
+    projected_candidates = project_to_5070(candidate_df)
+
+    presence_x = projected_presence["x_5070"].to_numpy(dtype=float)
+    presence_y = projected_presence["y_5070"].to_numpy(dtype=float)
+    candidate_x = projected_candidates["x_5070"].to_numpy(dtype=float)
+    candidate_y = projected_candidates["y_5070"].to_numpy(dtype=float)
+
+    min_distances = compute_min_distance_to_presence(candidate_x, candidate_y, presence_x, presence_y)
+    projected_candidates["distance_to_presence_m"] = min_distances
+
+    projected_candidates = projected_candidates[
+        projected_candidates["distance_to_presence_m"] >= exclusion_distance_m
+    ].copy()
+
+    if projected_candidates.empty:
+        raise RuntimeError(
+            f"No candidate background points remain after excluding all locations within {exclusion_distance_m} m of known {species_name} presences."
+        )
+
+    thinned_candidates = spatial_thin(
+        projected_candidates[["latitude", "longitude", "observation_id", "taxon_id", "taxon_name", "common_name"]].copy(),
+        thinning_distance_m,
+        random_state,
+    )
+
+    required_background = int(round(len(presence_df) * background_ratio))
+
+    if len(thinned_candidates) < required_background:
+        raise RuntimeError(
+            f"Too few candidate background points remain after filtering and thinning: {len(thinned_candidates)} available, {required_background} required."
+        )
+
+    rng = np.random.default_rng(random_state)
+    sample_indices = rng.choice(len(thinned_candidates), size=required_background, replace=False)
+    sample_df = thinned_candidates.iloc[sample_indices].reset_index(drop=True)
+
+    sample_df = sample_df[["latitude", "longitude"]].copy()
+    sample_df["presence"] = 0
+
+    background_file = samples_dir / f"{species_slug_value}_background.csv"
+    background_file.parent.mkdir(parents=True, exist_ok=True)
+    sample_df.to_csv(background_file, index=False)
+
+    training_df = pd.concat(
+        [
+            presence_df[["latitude", "longitude"]].copy().assign(presence=1),
+            sample_df[["latitude", "longitude", "presence"]].copy(),
+        ],
+        ignore_index=True,
+    )
+
+    training_df = training_df.sample(frac=1, random_state=random_state).reset_index(drop=True)
+
+    training_file = samples_dir / f"{species_slug_value}_training_points.csv"
+    training_file.parent.mkdir(parents=True, exist_ok=True)
+    training_df.to_csv(training_file, index=False)
+
+    return sample_df
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate target-group background points for a species in Massachusetts.",
+    )
+    parser.add_argument("--species", required=True, help="Species name, e.g. 'Fisher'.")
+    parser.add_argument("--background-ratio", type=float, default=3.0)
+    parser.add_argument("--exclusion-distance-m", type=float, default=1000)
+    parser.add_argument("--thinning-distance-m", type=float, default=500)
+    parser.add_argument("--refresh-pool", action="store_true")
+    args = parser.parse_args()
+
+    load_or_create_mammal_pool(refresh_pool=args.refresh_pool)
+
+    background_df = generate_background(
+        args.species,
+        background_ratio=args.background_ratio,
+        exclusion_distance_m=args.exclusion_distance_m,
+        thinning_distance_m=args.thinning_distance_m,
+    )
+
+    species_slug_value = species_slug(args.species)
+    background_file = Path(f"data/processed/samples/{species_slug_value}_background.csv")
+    training_file = Path(f"data/processed/samples/{species_slug_value}_training_points.csv")
+
+    print(f"Background points saved to: {background_file}")
+    print(f"Training points saved to: {training_file}")
+    print(f"Background rows: {len(background_df)}")
+
+
+if __name__ == "__main__":
+    main()