# -*- coding: utf-8 -*-
"""
HerpMap_SurveyZones.pyt - one tool that turns a HerpMap habitat-suitability mesh into
ranked survey-priority zones, chaining the whole manual workflow:

  1. Filter the mesh to high-suitability SURVEY TARGETS
       hsi >= cutoff, and optionally: no records (pres_n = 0), unsurveyed (effort_n = 0),
       expanding habitat (change = 'gain'), plus any extra SQL (e.g. a single run_label).
  2. Getis-Ord Gi* hot-spot analysis -> keep only STATISTICALLY SIGNIFICANT high clusters
       (90/95/99% confidence) so you are not chasing isolated lucky cells.
  3. DBSCAN density clustering -> group the surviving targets into DISCRETE zones, dropping noise.
  4. Convex-hull SURVEY ZONES with area_km2, mean HSI, mean Gi* z-score, a 0-1 PRIORITY score and RANK.

Works on the app export (habitat_mesh) and on the auto-synced server layer (hsm_mesh). For hsm_mesh,
which stores several runs, put the run in the Additional filter, e.g.:
    run_label = 'Drymarchon melanurus . 3km . run 1 (initial)'

Requires ArcGIS Pro (Spatial Statistics - core, no extension). Self-contained: no helper modules.
"""
import os
import arcpy

CONF_BIN = {"90%": 1, "95%": 2, "99%": 3}   # Gi_Bin cutoff for each confidence level


class Toolbox(object):
    def __init__(self):
        self.label = "HerpMap HSM Tools"
        self.alias = "herpmaphsm"
        self.tools = [SurveyPriorityZones]


class SurveyPriorityZones(object):
    def __init__(self):
        self.label = "HSM Survey Priority Zones"
        self.description = (
            "Turns a HerpMap habitat-suitability mesh into ranked survey-priority zones: filters to "
            "high-suitability survey targets, keeps statistically significant Getis-Ord Gi* hot spots, "
            "clusters them with DBSCAN, and builds convex-hull zones with area, mean HSI and a 0-1 priority score.")
        self.canRunInBackground = False

    # ------------------------------------------------------------------ parameters
    def getParameterInfo(self):
        in_mesh = arcpy.Parameter(displayName="Input HSM mesh (habitat_mesh / hsm_mesh)", name="in_mesh",
                                  datatype="GPFeatureLayer", parameterType="Required", direction="Input")
        in_mesh.filter.list = ["Polygon"]

        hsi = arcpy.Parameter(displayName="Suitability field", name="hsi_field", datatype="Field",
                              parameterType="Required", direction="Input")
        hsi.parameterDependencies = [in_mesh.name]
        hsi.filter.list = ["Short", "Long", "Float", "Double"]
        hsi.value = "hsi"

        thr = arcpy.Parameter(displayName="Minimum suitability (survey-target cutoff)", name="min_hsi",
                              datatype="GPDouble", parameterType="Required", direction="Input")
        thr.value = 0.9

        norec = arcpy.Parameter(displayName="Only cells with no records (pres_n = 0)", name="no_records",
                                datatype="GPBoolean", parameterType="Optional", direction="Input")
        norec.value = True

        unsurv = arcpy.Parameter(displayName="Only unsurveyed cells (effort_n = 0)", name="unsurveyed",
                                 datatype="GPBoolean", parameterType="Optional", direction="Input")
        unsurv.value = False

        expand = arcpy.Parameter(displayName="Only expanding habitat (change = 'gain')", name="expanding",
                                 datatype="GPBoolean", parameterType="Optional", direction="Input")
        expand.value = False

        extra = arcpy.Parameter(displayName="Additional filter (optional SQL, e.g. a single run_label)",
                                name="extra_sql", datatype="GPSQLExpression", parameterType="Optional", direction="Input")
        extra.parameterDependencies = [in_mesh.name]

        usegi = arcpy.Parameter(displayName="Require statistically significant hot spots (Getis-Ord Gi*)",
                                name="use_gi", datatype="GPBoolean", parameterType="Optional", direction="Input")
        usegi.value = True

        conf = arcpy.Parameter(displayName="Hot-spot confidence", name="gi_conf", datatype="GPString",
                               parameterType="Optional", direction="Input")
        conf.filter.type = "ValueList"
        conf.filter.list = ["90%", "95%", "99%"]
        conf.value = "95%"

        minc = arcpy.Parameter(displayName="DBSCAN - minimum cells per cluster", name="min_cluster",
                               datatype="GPLong", parameterType="Required", direction="Input")
        minc.value = 5

        dist = arcpy.Parameter(displayName="DBSCAN - search distance (blank = auto from cell size)",
                               name="search_dist", datatype="GPLinearUnit", parameterType="Optional", direction="Input")

        out = arcpy.Parameter(displayName="Output survey-priority zones", name="out_fc",
                              datatype="DEFeatureClass", parameterType="Required", direction="Output")

        return [in_mesh, hsi, thr, norec, unsurv, expand, extra, usegi, conf, minc, dist, out]

    def isLicensed(self):
        return True

    def updateParameters(self, parameters):
        p = {x.name: x for x in parameters}
        p["gi_conf"].enabled = bool(p["use_gi"].value)
        return

    def updateMessages(self, parameters):
        return

    # ------------------------------------------------------------------ execute
    def execute(self, parameters, messages):
        P = {x.name: x for x in parameters}
        arcpy.env.overwriteOutput = True
        scratch = arcpy.env.scratchGDB
        sg = lambda n: os.path.join(scratch, n)

        mesh = P["in_mesh"].valueAsText
        hsi = P["hsi_field"].valueAsText
        thr = P["min_hsi"].value
        out = P["out_fc"].valueAsText
        flds = {f.name.lower() for f in arcpy.ListFields(mesh)}

        # ---- isolate the run / subset the whole analysis runs on (so Gi* is per-run, not across runs)
        base_where = P["extra_sql"].valueAsText or None
        arcpy.management.MakeFeatureLayer(mesh, "herp_base", base_where)

        # ---- survey-target filter (field delimiters chosen per data source)
        def tw_for(ds):
            w = "%s >= %s" % (arcpy.AddFieldDelimiters(ds, hsi), thr)
            if P["no_records"].value and "pres_n" in flds:
                w += " AND %s = 0" % arcpy.AddFieldDelimiters(ds, "pres_n")
            if P["unsurveyed"].value and "effort_n" in flds:
                w += " AND %s = 0" % arcpy.AddFieldDelimiters(ds, "effort_n")
            if P["expanding"].value and "change" in flds:
                w += " AND %s = 'gain'" % arcpy.AddFieldDelimiters(ds, "change")
            return w
        arcpy.AddMessage("Survey-target filter: %s" % tw_for(mesh))

        # ---- Getis-Ord Gi* on the (run) mesh, then keep only significant targets
        Z_THRESH = {"90%": 1.645, "95%": 1.960, "99%": 2.576}
        conf = P["gi_conf"].value or "95%"
        z_f = None
        # Survey targets always come from the mesh, which carries hsi / pres_n / effort_n / change.
        arcpy.management.MakeFeatureLayer("herp_base", "herp_targets", tw_for(mesh))
        src = mesh
        carry = [hsi]
        if P["use_gi"].value:
            gi = sg("herp_gi")
            arcpy.AddMessage("Running Getis-Ord Gi* hot-spot analysis (contiguity, FDR corrected)...")
            # Contiguity (adjacent hexes) suits a regular mesh and needs no distance band.
            # Gi* keeps only the analysis field, so filter significance on the Gi* output (Gi_Bin),
            # then keep the survey targets that land on a significant hot-spot cell.
            arcpy.stats.HotSpots("herp_base", hsi, gi, "CONTIGUITY_EDGES_CORNERS",
                                 "EUCLIDEAN_DISTANCE", "NONE", None, None, None, "APPLY_FDR")
            gf = [f.name for f in arcpy.ListFields(gi)]
            bin_f = next((f for f in gf if "bin" in f.lower()), None)
            z2 = next((f for f in gf if "zscore" in f.lower() or f.lower().startswith("giz")), None)
            if bin_f:
                sigwhere = "%s >= %d" % (arcpy.AddFieldDelimiters(gi, bin_f), CONF_BIN[conf])
            elif z2:
                sigwhere = "%s >= %s" % (arcpy.AddFieldDelimiters(gi, z2), Z_THRESH[conf])
            else:
                raise arcpy.ExecuteError(
                    "Hot Spot Analysis returned no bin or z-score field. Fields found: %s" % ", ".join(gf))
            arcpy.management.MakeFeatureLayer(gi, "herp_sig", sigwhere)
            arcpy.AddMessage("%s significant hot-spot cells (%s)."
                             % (arcpy.management.GetCount("herp_sig")[0], conf))
            arcpy.management.SelectLayerByLocation("herp_targets", "HAVE_THEIR_CENTER_IN", "herp_sig")

        n = int(arcpy.management.GetCount("herp_targets")[0])
        arcpy.AddMessage("%d survey-target cells after filtering." % n)
        if n < P["min_cluster"].value:
            raise arcpy.ExecuteError(
                "Only %d cells passed the filter - fewer than the minimum cluster size. "
                "Lower the suitability cutoff or the confidence, or turn off a filter." % n)

        # ---- centroids carrying hsi; license-free (avoids Feature To Point / Advanced)
        pts = sg("herp_pts")
        sr = arcpy.Describe("herp_targets").spatialReference
        arcpy.management.CreateFeatureclass(scratch, "herp_pts", "POINT", spatial_reference=sr)
        numeric = ("Double", "Single", "Integer", "SmallInteger", "OID")
        for fld in carry:
            ft = next(f.type for f in arcpy.ListFields(src) if f.name == fld)
            arcpy.management.AddField(pts, fld, "DOUBLE" if ft in numeric else "TEXT")
        xs, ys = [], []
        with arcpy.da.SearchCursor("herp_targets", ["SHAPE@XY"] + carry) as sc, \
                arcpy.da.InsertCursor(pts, ["SHAPE@XY"] + carry) as ic:
            for row in sc:
                ic.insertRow(row)
                xs.append(row[0][0]); ys.append(row[0][1])

        # ---- cluster in a metric projection so DBSCAN distances are real meters
        if sr.type == "Geographic":
            cx = sum(xs) / len(xs); cy = sum(ys) / len(ys)
            zone = int((cx + 180.0) / 6.0) + 1          # local UTM zone -> metric distances for DBSCAN
            metric_sr = arcpy.SpatialReference((32600 if cy >= 0 else 32700) + zone)
            pts_m = sg("herp_pts_m")
            arcpy.management.Project(pts, pts_m, metric_sr)
        else:
            pts_m = pts

        # ---- DBSCAN search distance: auto from the mesh's geodesic cell size if left blank
        dist = P["search_dist"].valueAsText
        if not dist:
            am2 = sorted(g.getArea("GEODESIC", "SQUAREMETERS")
                         for g in [r[0] for r in arcpy.da.SearchCursor("herp_base", ["SHAPE@"])][:300] if g)
            med = am2[len(am2) // 2] if am2 else 9.0e6
            dist = "%f Meters" % max(100.0, 2.5 * (med ** 0.5))
        arcpy.AddMessage("DBSCAN search distance: %s" % dist)

        # ---- DBSCAN; re-attach hsi if the tool dropped the input fields
        clustered = sg("herp_clusters")
        arcpy.stats.DensityBasedClustering(pts_m, clustered, "DBSCAN", P["min_cluster"].value, dist)
        cf = {f.name.lower() for f in arcpy.ListFields(clustered)}
        if hsi.lower() not in cf and "source_id" in cf:
            arcpy.management.JoinField(clustered, "SOURCE_ID", pts_m, arcpy.Describe(pts_m).OIDFieldName, carry)

        # ---- drop noise, per-cluster stats
        arcpy.management.MakeFeatureLayer(clustered, "herp_clu", '"CLUSTER_ID" <> -1')
        if int(arcpy.management.GetCount("herp_clu")[0]) == 0:
            raise arcpy.ExecuteError("DBSCAN found no clusters (all points were noise). "
                                     "Increase the search distance or lower the minimum cells per cluster.")
        stats = sg("herp_stats")
        arcpy.analysis.Statistics("herp_clu", stats, [[hsi, "MEAN"], [hsi, "MAX"]], "CLUSTER_ID")

        # ---- convex-hull survey zones (one per cluster), then stats, area, 0-1 priority + rank
        zones = sg("herp_zones")
        arcpy.management.MinimumBoundingGeometry("herp_clu", zones, "CONVEX_HULL", "LIST", "CLUSTER_ID")
        mean_hsi = "MEAN_%s" % hsi
        arcpy.management.JoinField(zones, "CLUSTER_ID", stats, "CLUSTER_ID", [mean_hsi, "MAX_%s" % hsi])
        arcpy.management.AddField(zones, "area_km2", "DOUBLE")
        arcpy.management.CalculateGeometryAttributes(zones, [["area_km2", "AREA_GEODESIC"]],
                                                     area_unit="SQUARE_KILOMETERS")
        comps = ["area_km2", mean_hsi]
        rows = [list(r) for r in arcpy.da.SearchCursor(zones, ["OID@"] + comps)]
        rng = {}
        for i2, c in enumerate(comps, start=1):
            vals = [r[i2] for r in rows if r[i2] is not None]
            rng[c] = (min(vals), max(vals)) if vals else (0.0, 1.0)
        scores = {}
        for r in rows:
            tot, k = 0.0, 0
            for i2, c in enumerate(comps, start=1):
                lo, hi = rng[c]; v = r[i2]
                if v is None:
                    continue
                tot += (v - lo) / (hi - lo) if hi > lo else 1.0; k += 1
            scores[r[0]] = tot / k if k else 0.0
        order = sorted(scores, key=lambda o: scores[o], reverse=True)
        rankof = {o: n2 + 1 for n2, o in enumerate(order)}
        arcpy.management.AddField(zones, "PRIORITY", "DOUBLE")
        arcpy.management.AddField(zones, "RANK", "LONG")
        with arcpy.da.UpdateCursor(zones, ["OID@", "PRIORITY", "RANK"]) as uc:
            for row in uc:
                row[1] = round(scores[row[0]], 4); row[2] = rankof[row[0]]; uc.updateRow(row)

        # ---- deliver in the mesh's coordinate system
        if sr.type == "Geographic":
            arcpy.management.Project(zones, out, sr)
        else:
            arcpy.management.CopyFeatures(zones, out)
        arcpy.AddMessage("Done: %d survey-priority zones written to %s "
                         "(fields: area_km2, %s, PRIORITY, RANK)." % (len(order), out, mean_hsi))
        return
