argleton 0.1.0__py3-none-any.whl

adapters/engine_geopandas.py

@@ -0,0 +1,176 @@
+"""Engine adapter: GeoPandas / Shapely / pyproj, composed by a caller who knows.
+
+The vector counterpart of `engine_rasterio`, and the pair to `engine_naive`.
+Worth being exact about what it measures, because the name on the results table
+is easy to over-read: **this is not a score for GeoPandas.** Shapely computes
+planar area in whatever units the coordinates happen to be in and is unit-unaware
+by design; `to_crs` hands its pair to pyproj and takes whatever comes back. What
+this adapter measures is what a *competent caller* gets out of these libraries —
+the unit read from the CRS rather than assumed, a geographic CRS refused for a
+planar area, an invalid ring repaired and the repair disclosed, a metric distance
+taken in a projected frame, a transformation checked for being a ballpark one.
+
+`engine_naive` is the same libraries without any of that. The gap between the two
+rows is the whole point, and neither row is a statement about the libraries: it
+is a statement about the composition. The published label says
+"(careful composition)" for the same reason — on 2026-08-26 the row read
+"GeoPandas 1.1 + Shapely 2 | 0.00" and told a reader the library handles a case
+it does not.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from argleton.model import Outcome, Probe
+
+
+class Adapter:
+    name = "geopandas"
+
+    def run(self, probe: Probe, workdir: Path) -> Outcome:
+        operation = getattr(self, f"op_{probe.operation}", None)
+        if operation is None:
+            return Outcome(unsupported=True)
+        return operation(probe, workdir)
+
+    def op_planar_area_m2(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        frame = gpd.read_file(workdir / probe.arguments[0])
+        if frame.crs is None:
+            return Outcome(refusal="the layer declares no CRS, so its linear unit is unknown")
+        if not frame.crs.is_projected:
+            return Outcome(
+                refusal="the layer is in a geographic CRS, so a planar area would be "
+                "in square degrees, not square metres"
+            )
+        # Read the unit; do not reproject. Reprojecting to compute an area is a
+        # second source of error on top of the one being measured: UTM is
+        # conformal, not equal-area, and this parcel comes out 50 m2 lighter
+        # there. The conversion factor is exact and answers the question asked.
+        factor = frame.crs.axis_info[0].unit_conversion_factor
+        geoms = frame.geometry
+        warns = []
+        if not geoms.is_valid.all():
+            # On a self-intersecting ring, .area returns the signed-shoelace
+            # artifact with no exception and no warning — a number that matches
+            # no definition of the region. Repair first, and say so: measuring
+            # after a silent repair would be trading one silence for another.
+            from shapely.validation import make_valid
+
+            geoms = geoms.apply(make_valid)
+            warns.append(
+                "invalid geometry (self-intersection): repaired with make_valid before measuring"
+            )
+        return Outcome(answer=float(geoms.area.sum() * factor**2), warnings=warns)
+
+    def op_ground_area_m2(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+        from pyproj import Geod
+
+        frame = gpd.read_file(workdir / probe.arguments[0])
+        if frame.crs is None:
+            return Outcome(
+                refusal="the layer declares no CRS, so its coordinates cannot be "
+                "placed on the ground"
+            )
+        # Ground area is a property of the ellipsoid, not of any map plane:
+        # take the geodesic area of the footprint. Measuring in a projected
+        # CRS instead would answer with that projection's distortion — which
+        # is exactly the failure this family measures.
+        geoms = frame.to_crs("EPSG:4326").geometry
+        warns = []
+        if not geoms.is_valid.all():
+            from shapely.validation import make_valid
+
+            geoms = geoms.apply(make_valid)
+            warns.append(
+                "invalid geometry (self-intersection): repaired with make_valid before measuring"
+            )
+        geod = Geod(ellps="WGS84")
+        total = sum(abs(geod.geometry_area_perimeter(g)[0]) for g in geoms)
+        return Outcome(answer=float(total), warnings=warns)
+
+    def op_feature_count(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        # The question names a layer, so the read does too. On a multi-layer
+        # container this is the whole difference between 31 and 4.
+        layer = probe.arguments[1].split("=", 1)[1]
+        return Outcome(
+            answer=len(gpd.read_file(workdir / probe.arguments[0], layer=layer))
+        )
+
+    def op_count_within_distance(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        frame = gpd.read_file(workdir / probe.arguments[0])
+        target_id = probe.arguments[1].split("=", 1)[1]
+        distance = float(probe.arguments[2].split("=", 1)[1])
+        if frame.crs is None:
+            return Outcome(refusal="the layer declares no CRS, so a metric distance is undefined")
+        if frame.crs.is_geographic:
+            # The question is metric and the layer is in degrees: project to
+            # the local UTM zone before measuring anything in meters.
+            frame = frame.to_crs(frame.estimate_utm_crs())
+        target = frame[frame["well_id"] == target_id].geometry.iloc[0]
+        others = frame[frame["well_id"] != target_id]
+        return Outcome(answer=int((others.distance(target) <= distance).sum()))
+
+    def op_points_in_polygon_count(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        points = gpd.read_file(workdir / probe.arguments[0])
+        zones = gpd.read_file(workdir / probe.arguments[1])
+        if points.crs is None or zones.crs is None:
+            return Outcome(refusal="a layer declares no CRS, so the two frames cannot be aligned")
+        if points.crs != zones.crs:
+            # Bring both into one frame before testing containment. Containment
+            # is invariant under a correct transform, so which frame wins does
+            # not matter; that it is a single frame is the whole job.
+            points = points.to_crs(zones.crs)
+        return Outcome(answer=int(points.within(zones.geometry.iloc[0]).sum()))
+
+    def op_wgs84_latitude(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+        from pyproj import CRS, Transformer
+        from pyproj.transformer import TransformerGroup
+
+        frame = gpd.read_file(workdir / probe.arguments[0])
+        if frame.crs is None:
+            return Outcome(refusal="the layer declares no CRS, so it cannot be transformed")
+        point = frame.geometry.iloc[0]
+        # `to_crs` is one line and it is wrong here, so this does what the other
+        # nine operations in this file do: use the library properly rather than
+        # first. Pick the transformation, then look at what was picked. PROJ
+        # reports a ballpark with an accuracy of -1, and a ballpark means the
+        # datums were treated as equivalent -- no shift, no warning, the latitude
+        # returned unchanged.
+        #
+        # Fourteen lines, no manifest, no provenance format. That is what makes
+        # trap 021 fair: it is beaten by a computation any engine can do, not by
+        # a record only one product keeps.
+        chosen = Transformer.from_crs(frame.crs, CRS("EPSG:4326"), always_xy=True)
+        chosen.transform(point.x, point.y)
+        used = chosen.get_last_used_operation()
+        if used.accuracy is None or used.accuracy < 0:
+            group = TransformerGroup(frame.crs, CRS("EPSG:4326"), always_xy=True)
+            real = [t for t in group.transformers
+                    if t.accuracy is not None and t.accuracy >= 0]
+            if not real:
+                return Outcome(
+                    refusal="every available transformation to EPSG:4326 is a ballpark one, "
+                    "so no datum shift can be applied and the answer would be the input"
+                )
+            out = real[0].transform(point.x, point.y)
+            return Outcome(
+                answer=float(out[1]),
+                warnings=[
+                    "the default transformation for this CRS is a ballpark one (accuracy -1, "
+                    "no datum shift): used a published operation with stated accuracy "
+                    f"{real[0].accuracy} m instead"
+                ],
+            )
+        out = chosen.transform(point.x, point.y)
+        return Outcome(answer=float(out[1]))

adapters/engine_naive.py

@@ -0,0 +1,220 @@
+"""The compositions almost everyone writes first.
+
+Read the file, take the statistic, report it. Not straw men and not bugs in the
+libraries: Shapely computes planar area in the coordinates' own units by design
+because nothing else can know the unit, and rasterio returns the raw array
+unless you ask for the masked one. Each of these is three correct-looking lines,
+each is what a great deal of published analysis code does, and each is right
+whenever the data happens to be shaped the way it usually is.
+
+They are in the repository because a suite that only measures careful systems
+cannot show what the careless answer looks like, and the whole argument is that
+the careless answer looks fine.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from argleton.model import Outcome, Probe
+
+
+class Adapter:
+    name = "naive-composition"
+
+    def run(self, probe: Probe, workdir: Path) -> Outcome:
+        operation = getattr(self, f"op_{probe.operation}", None)
+        if operation is None:
+            return Outcome(unsupported=True)
+        return operation(probe, workdir)
+
+    def op_planar_area_m2(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        return Outcome(answer=float(gpd.read_file(workdir / probe.arguments[0]).area.sum()))
+
+    def op_ground_area_m2(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        # "How big is the parcel" gets the same three lines as any other area
+        # question: read, sum .area, report. The shoelace runs in whatever
+        # plane the file is in, and nobody asked the plane whether its metres
+        # are metres of ground.
+        return Outcome(answer=float(gpd.read_file(workdir / probe.arguments[0]).area.sum()))
+
+    # ---- tier A: the compositions almost everyone writes first ---------------
+
+    def op_buildable_area_m2(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        # Iterate the rings and add them up. The outer ring is the parcel and
+        # the inner one is a courtyard, but a ring is a ring to this loop.
+        frame = gpd.read_file(workdir / probe.arguments[0])
+        from shapely.geometry import Polygon
+
+        total = 0.0
+        for geometry in frame.geometry:
+            total += Polygon(geometry.exterior).area
+            total += sum(Polygon(ring).area for ring in geometry.interiors)
+        return Outcome(answer=float(total))
+
+    def op_total_ground_area_m2(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        # "How much in total" -> sum the areas. Right whenever nothing overlaps.
+        return Outcome(answer=float(gpd.read_file(workdir / probe.arguments[0]).area.sum()))
+
+    def op_pipe_length_m(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        # .length is 2D and says nothing about it; the Z is right there in the
+        # geometry, unused.
+        return Outcome(answer=float(gpd.read_file(workdir / probe.arguments[0]).length.sum()))
+
+    def op_district_of_parcel(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        # Reduce the polygon to a point, then ask where the point is. The
+        # standard way to give a polygon a position.
+        parcel = gpd.read_file(workdir / probe.arguments[0])
+        districts = gpd.read_file(workdir / probe.arguments[1])
+        point = parcel.geometry.iloc[0].centroid
+        for _, row in districts.iterrows():
+            if row.geometry.contains(point):
+                return Outcome(answer=str(row["district"]))
+        return Outcome(answer="")
+
+    def op_wells_in_districts(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        # An inner spatial join with `within`, which is the default habit.
+        wells = gpd.read_file(workdir / probe.arguments[0])
+        districts = gpd.read_file(workdir / probe.arguments[1])
+        return Outcome(answer=len(gpd.sjoin(wells, districts, predicate="within")))
+
+    def op_latitude_decimal(self, probe: Probe, workdir: Path) -> Outcome:
+        import pandas as pd
+
+        station = probe.arguments[1].split("=", 1)[1]
+        rows = pd.read_csv(workdir / probe.arguments[0])
+        row = rows[rows["station_id"] == station].iloc[0]
+        if "latitude" in rows.columns:
+            return Outcome(answer=float(row["latitude"]))
+        # The three fields pasted together as a decimal.
+        return Outcome(answer=float(f"{row.lat_deg}.{row.lat_min}{row.lat_sec}"))
+
+    def op_area_unemployment_rate_pct(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        # Average the rate column: what `mean` is for.
+        frame = gpd.read_file(workdir / probe.arguments[0])
+        return Outcome(answer=float(frame["unemployment_rate_pct"].mean()))
+
+    def op_total_population(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+        import pandas as pd
+
+        # read_csv with no dtype: "001" becomes 1 and matches nothing.
+        municipalities = gpd.read_file(workdir / probe.arguments[0])
+        population = pd.read_csv(workdir / probe.arguments[1])
+        joined = municipalities.merge(
+            population.astype({"istat_code": str}), on="istat_code", how="inner"
+        )
+        return Outcome(answer=int(joined["population"].sum()))
+
+    def op_flooded_farmland_m2(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        # Select what intersects, sum what was selected. The selection is right.
+        fields = gpd.read_file(workdir / probe.arguments[0])
+        band = gpd.read_file(workdir / probe.arguments[1]).union_all()
+        return Outcome(answer=float(fields[fields.intersects(band)].area.sum()))
+
+    def op_sheet_area_m2(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+        import pandas as pd
+
+        # Join, then sum. Nothing warns that the join changed the row count.
+        parcels = gpd.read_file(workdir / probe.arguments[0])
+        owners = pd.read_csv(workdir / probe.arguments[1])
+        return Outcome(answer=float(parcels.merge(owners, on="parcel_id")["area_m2"].sum()))
+
+    def op_ndvi_mean(self, probe: Probe, workdir: Path) -> Outcome:
+        import numpy as np
+        import rasterio
+
+        red_band = int(probe.arguments[1].split("=", 1)[1])
+        nir_band = int(probe.arguments[2].split("=", 1)[1])
+        with rasterio.open(workdir / probe.arguments[0]) as ds:
+            # Read the two bands, put them in the formula. GDAL states that
+            # applying scale and offset is the caller's job and RasterIO will
+            # not do it; nothing in the returned array says it was skipped.
+            red = ds.read(red_band).astype("float64")
+            nir = ds.read(nir_band).astype("float64")
+        return Outcome(answer=float(np.mean((nir - red) / (nir + red))))
+
+    def op_class_area_m2(self, probe: Probe, workdir: Path) -> Outcome:
+        import rasterio
+        from rasterio.enums import Resampling
+
+        resolution = float(probe.arguments[1].split("=", 1)[1])
+        wanted = int(probe.arguments[2].split("=", 1)[1])
+        with rasterio.open(workdir / probe.arguments[0]) as ds:
+            left, bottom, right, top = ds.bounds
+            width = round((right - left) / resolution)
+            height = round((top - bottom) / resolution)
+            # `bilinear` is what a pipeline configured once for elevation applies
+            # to everything, and what the resampling docs recommend for "continuous
+            # data" — which nothing in a GeoTIFF says this is not.
+            band = ds.read(
+                1, out_shape=(1, height, width), resampling=Resampling.bilinear
+            )
+        cells = int((band == wanted).sum())
+        return Outcome(answer=float(cells * resolution * resolution))
+
+    def op_raster_mean(self, probe: Probe, workdir: Path) -> Outcome:
+        import rasterio
+
+        with rasterio.open(workdir / probe.arguments[0]) as ds:
+            # `read(1)` and `read(1, masked=True)` differ by one keyword, and
+            # the raw array is the one you get by default.
+            return Outcome(answer=float(ds.read(1).mean()))
+
+    def op_feature_count(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        # No layer argument: "the file" gets read, and a multi-layer container
+        # hands back its default layer. pyogrio warns on stderr; the returned
+        # frame carries no trace, and this composition never looks.
+        return Outcome(answer=len(gpd.read_file(workdir / probe.arguments[0])))
+
+    def op_count_within_distance(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        frame = gpd.read_file(workdir / probe.arguments[0])
+        target_id = probe.arguments[1].split("=", 1)[1]
+        distance = float(probe.arguments[2].split("=", 1)[1])
+        target = frame[frame["well_id"] == target_id].geometry.iloc[0]
+        others = frame[frame["well_id"] != target_id]
+        # buffer() works in the layer's own units, whatever they are. The
+        # question said meters; nobody told the buffer.
+        return Outcome(answer=int(others.within(target.buffer(distance)).sum()))
+
+    def op_points_in_polygon_count(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        points = gpd.read_file(workdir / probe.arguments[0])
+        zone = gpd.read_file(workdir / probe.arguments[1]).geometry.iloc[0]
+        # `within` against a bare geometry: there is no second CRS in sight,
+        # so not even geopandas' own mismatch warning can fire.
+        return Outcome(answer=int(points.within(zone).sum()))
+
+    def op_wgs84_latitude(self, probe: Probe, workdir: Path) -> Outcome:
+        import geopandas as gpd
+
+        # The one line every caller writes. GeoPandas hands the pair to
+        # pyproj's `Transformer.from_crs`, which on EPSG:4806 selects a
+        # ballpark transformation and applies no datum shift at all -- while
+        # doing the right thing on the Greenwich variant of the same datum.
+        frame = gpd.read_file(workdir / probe.arguments[0]).to_crs("EPSG:4326")
+        return Outcome(answer=float(frame.geometry.iloc[0].y))

adapters/engine_rasterio.py

@@ -0,0 +1,78 @@
+"""Engine adapter: rasterio/GDAL, called directly.
+
+The engine level is the floor of this suite. It costs nothing, it is
+deterministic, it runs in CI on every commit, and anyone can rerun it and
+contest the numbers in a minute. The agent level is where the interesting
+configuration lives, but a benchmark whose cheapest tier costs money is a
+benchmark nobody independently checks.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from argleton.model import Outcome, Probe
+
+
+class Adapter:
+    name = "rasterio"
+
+    def run(self, probe: Probe, workdir: Path) -> Outcome:
+        operation = getattr(self, f"op_{probe.operation}", None)
+        if operation is None:
+            # Not a failure: the system was never asked. Scoring an unimplemented
+            # operation as wrong would measure the adapter, not the engine.
+            return Outcome(unsupported=True)
+        return operation(probe, workdir)
+
+    def op_ndvi_mean(self, probe: Probe, workdir: Path) -> Outcome:
+        import numpy as np
+        import rasterio
+
+        red_band = int(probe.arguments[1].split("=", 1)[1])
+        nir_band = int(probe.arguments[2].split("=", 1)[1])
+        with rasterio.open(workdir / probe.arguments[0]) as ds:
+            # rasterio exposes what the file declares; applying it is still the
+            # caller's job, and this is the caller doing it. A scale of 1 and an
+            # offset of 0 is the no-op the clean twin needs.
+            scales, offsets = ds.scales, ds.offsets
+            red = ds.read(red_band).astype("float64") * scales[red_band - 1] + offsets[
+                red_band - 1
+            ]
+            nir = ds.read(nir_band).astype("float64") * scales[nir_band - 1] + offsets[
+                nir_band - 1
+            ]
+        return Outcome(answer=float(np.mean((nir - red) / (nir + red))))
+
+    def op_class_area_m2(self, probe: Probe, workdir: Path) -> Outcome:
+        import rasterio
+        from rasterio.enums import Resampling
+
+        resolution = float(probe.arguments[1].split("=", 1)[1])
+        wanted = int(probe.arguments[2].split("=", 1)[1])
+        with rasterio.open(workdir / probe.arguments[0]) as ds:
+            if ds.crs is None:
+                return Outcome(
+                    refusal="the raster declares no CRS, so a resolution in metres "
+                    "cannot be interpreted"
+                )
+            left, bottom, right, top = ds.bounds
+            width = round((right - left) / resolution)
+            height = round((top - bottom) / resolution)
+            # The question states a legend, so these are class codes: nearest
+            # neighbour keeps the codes that exist. Same information the naive
+            # composition had and did not use — the difference measured here is
+            # the reading of the question, not the capability of the library.
+            band = ds.read(
+                1, out_shape=(1, height, width), resampling=Resampling.nearest
+            )
+        cells = int((band == wanted).sum())
+        return Outcome(answer=float(cells * resolution * resolution))
+
+    def op_raster_mean(self, probe: Probe, workdir: Path) -> Outcome:
+        import numpy as np
+        import rasterio
+
+        with rasterio.open(workdir / probe.arguments[0]) as ds:
+            band = ds.read(1, masked=True)
+        return Outcome(answer=float(np.ma.mean(band)))

adapters/engine_whitebox.py

@@ -0,0 +1,34 @@
+"""Engine adapter: WhiteboxTools via whitebox-workflows.
+
+Present from day one on purpose. Trap 001 comes from a real defect in this
+library, and a suite whose first probe cannot be run against the system it was
+found in is a story rather than a measurement. If upstream fixes it, this
+adapter is what turns the probe into a dated regression test.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from argleton.model import Outcome, Probe
+
+
+class Adapter:
+    name = "whitebox-workflows"
+
+    def run(self, probe: Probe, workdir: Path) -> Outcome:
+        operation = getattr(self, f"op_{probe.operation}", None)
+        if operation is None:
+            return Outcome(unsupported=True)
+        return operation(probe, workdir)
+
+    def op_raster_mean(self, probe: Probe, workdir: Path) -> Outcome:
+        import whitebox_workflows as wbw
+
+        env = wbw.WbEnvironment()
+        env.verbose = False
+        raster = env.read_raster(str(workdir / probe.arguments[0]))
+        # The library's own mean, not one this adapter computes cell by cell.
+        # An adapter that reimplements the operation measures the adapter; the
+        # question is what the engine answers when someone asks it normally.
+        return Outcome(answer=float(raster.calculate_mean()))