env-able 2.0.1__tar.gz → 2.1.0__tar.gz

{env_able-2.0.1 → env_able-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: env-able
-Version: 2.0.1
+Version: 2.1.0
 Summary: AI-ready GIS toolkit for energy and subsurface workflows.
 License: MIT
 License-File: LICENSE
@@ -235,6 +235,14 @@ Lines and polygons with fewer vertices, no edge moved more than `tolerance`. Mea
 result = env.Simplify("counties.shp", 200, "meters", output="counties_light.gpkg")
 ```
 
+### `env.SummaryStatistics(input_table, statistics_fields, case_field=None, output=None, separator=", ")`
+ArcGIS Pro's Summary Statistics: one row per unique set of `case_field` values, with each statistic asked for, as a **table** (no geometry). The input is a path, a DataFrame or a GeoDataFrame. The statistics are Dissolve's plus `MODE`; a text field takes only `MIN`, `MAX`, `COUNT`, `FIRST`, `LAST`, `UNIQUE`, `CONCATENATE` and `MODE`. Columns are named `SUM_EUR`, and blanks are left out of every statistic.
+
+```python
+result = env.SummaryStatistics("wells.gpkg", [["EUR", "SUM"], ["API", "COUNT"]], case_field="OPERATOR")
+result.gdf          # a pandas DataFrame, one row per operator
+```
+
 ---
 
 ### `env.load(source)` — fluent spatial pipeline

{env_able-2.0.1 → env_able-2.1.0}/README.md

@@ -209,6 +209,14 @@ Lines and polygons with fewer vertices, no edge moved more than `tolerance`. Mea
 result = env.Simplify("counties.shp", 200, "meters", output="counties_light.gpkg")
 ```
 
+### `env.SummaryStatistics(input_table, statistics_fields, case_field=None, output=None, separator=", ")`
+ArcGIS Pro's Summary Statistics: one row per unique set of `case_field` values, with each statistic asked for, as a **table** (no geometry). The input is a path, a DataFrame or a GeoDataFrame. The statistics are Dissolve's plus `MODE`; a text field takes only `MIN`, `MAX`, `COUNT`, `FIRST`, `LAST`, `UNIQUE`, `CONCATENATE` and `MODE`. Columns are named `SUM_EUR`, and blanks are left out of every statistic.
+
+```python
+result = env.SummaryStatistics("wells.gpkg", [["EUR", "SUM"], ["API", "COUNT"]], case_field="OPERATOR")
+result.gdf          # a pandas DataFrame, one row per operator
+```
+
 ---
 
 ### `env.load(source)` — fluent spatial pipeline

{env_able-2.0.1 → env_able-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "env-able"
-version = "2.0.1"
+version = "2.1.0"
 description = "AI-ready GIS toolkit for energy and subsurface workflows."
 readme = "README.md"
 requires-python = ">=3.8"

{env_able-2.0.1 → env_able-2.1.0}/src/env_able/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.0.1"
+__version__ = "2.1.0"
 
 # Resolve GDAL_DATA / PROJ_LIB before anything imports osgeo. IDEs and bare
 # `python script.py` runs skip conda's activation scripts, which is where those
@@ -9,8 +9,9 @@ _gdal_env.configure()
 
 from .vector import (
     Clip, Buffer, Intersect, Union, Dissolve, Near, SpatialJoin, Erase, Simplify,
+    SummaryStatistics,
     clip_async, buffer_async, intersect_async, union_async, dissolve_async,
-    near_async, spatial_join_async, erase_async, simplify_async,
+    near_async, spatial_join_async, erase_async, simplify_async, summary_statistics_async,
     SJ_MATCH,
     load,
 )

{env_able-2.0.1 → env_able-2.1.0}/src/env_able/atlas/calc.py

@@ -5,8 +5,12 @@ Calculate Field: one expression, evaluated per row, with nothing else reachable.
     calc.compile_expr("!NAME!.upper()", fields)
 
 ArcGIS Pro's syntax, so an expression copied out of Pro works here: a field is written
-`!FIELD!`. A bare name works too when it is a field (`EUR * 1000`), because that is what people
-type first.
+`!FIELD!`. ArcMap's `[FIELD]` works too, because people still type it, and so does a bare name
+when it is a field (`EUR * 1000`), because that is what people type first.
+
+A null propagates: `!EUR! * 1000` on a row with no EUR gives no value rather than failing the
+whole calculation on that row, and a comparison against a null is false. That is what a database
+does, and it is what someone calculating a 30,000-row column with a few blanks in it expects.
 
 It is Python's grammar, NOT Python. The expression is parsed with `ast` and walked by an
 interpreter that knows a short list of node types; anything else -- attribute access other than
@@ -18,15 +22,50 @@ model may have been handed by a document it was asked to read.
 from __future__ import annotations
 
 import ast
+import keyword
 import math
 import operator
 import re
 
+def _iif(test, a, b):                    # never called: ev() evaluates only the branch taken
+    return a if test else b
+
+
 FUNCS = {
     "abs": abs, "round": round, "min": min, "max": max, "len": len,
     "str": str, "int": int, "float": float, "bool": bool,
     "sqrt": math.sqrt, "floor": math.floor, "ceil": math.ceil, "log": math.log,
     "log10": math.log10, "exp": math.exp,
+    #  The function forms people know from ArcMap and from spreadsheets. iif is lazy, so
+    #  iif(!N! != 0, 1 / !N!, 0) does not divide by zero on the rows it is guarding.
+    "iif": _iif, "upper": str.upper, "lower": str.lower, "trim": str.strip,
+}
+#: Functions that pass a null through rather than tripping over it. bool and iif decide what a
+#: null means themselves, so they are not in it.
+_NULL_SAFE = set(FUNCS) - {"bool", "iif"}
+
+#: One line each, for the expression box's suggestions. Every function and method is listed;
+#: verify.py checks the two agree, so a function cannot be added without its help.
+HELP = {
+    "abs": ("abs(x)", "the value without its sign"),
+    "round": ("round(x, n)", "x to n decimal places"),
+    "min": ("min(a, b)", "the smaller value"),
+    "max": ("max(a, b)", "the larger value"),
+    "len": ("len(text)", "how many characters"),
+    "str": ("str(x)", "x as text"),
+    "int": ("int(x)", "x as a whole number"),
+    "float": ("float(x)", "x as a number"),
+    "bool": ("bool(x)", "true or false"),
+    "sqrt": ("sqrt(x)", "square root"),
+    "floor": ("floor(x)", "round down"),
+    "ceil": ("ceil(x)", "round up"),
+    "log": ("log(x)", "natural logarithm"),
+    "log10": ("log10(x)", "base-10 logarithm"),
+    "exp": ("exp(x)", "e to the power x"),
+    "iif": ("iif(test, a, b)", "a when test is true, otherwise b"),
+    "upper": ("upper(text)", "capitals"),
+    "lower": ("lower(text)", "lower case"),
+    "trim": ("trim(text)", "without leading and trailing spaces"),
 }
 #: Methods a string may be asked for. Each returns a string, a bool or an int, so a chain of
 #: them cannot reach anything that is not data.
@@ -79,6 +118,26 @@ def compile_expr(expr: str, fields):
         return slots[real]
 
     src = re.sub(r"!([^!]+)!", sub, src)
+
+    def sub_bracket(m):
+        #  [NAME] is a field only when NAME is one, and only where a value could start: after a
+        #  name, a closing bracket or a quote it is a subscript (!NAME![0], !NAME![:3]), which
+        #  is Python's and stays Python's.
+        before = src[:m.start()].rstrip()
+        word = re.search(r"[A-Za-z_]\w*$", before)
+        #  ...except after a keyword: `not [ID] == 3` is a value, though `not` ends in a letter.
+        if before and (before[-1].isalnum() or before[-1] in "_)]'\"") and not (
+                word and keyword.iskeyword(word.group(0))):
+            return m.group(0)
+        name = m.group(1).strip()
+        real = name if name in fields else lookup.get(name.lower())
+        if real is None:
+            return m.group(0)
+        if real not in slots:
+            slots[real] = _field_token(len(slots))
+        return slots[real]
+
+    src = re.sub(r"\[([^\[\]]+)\]", sub_bracket, src)
     try:
         tree = ast.parse(src, mode="eval")
     except SyntaxError as e:
@@ -95,6 +154,12 @@ def compile_expr(expr: str, fields):
                 if n.id in fields or n.id.lower() in lookup:
                     continue
                 raise CalcError("%r is not a field or a function. Write a field as !NAME!." % n.id)
+            elif isinstance(n, ast.List):
+                #  What a [NAME] that matched no field parses as. Saying "List is not allowed"
+                #  about a typo in a field name would send somebody looking in the wrong place.
+                if len(n.elts) == 1 and isinstance(n.elts[0], ast.Name):
+                    raise CalcError("[%s] is not a field in this layer." % n.elts[0].id)
+                raise CalcError("A list is not allowed in a field calculation.")
             elif isinstance(n, ast.Attribute):
                 if n.attr not in STR_METHODS:
                     raise CalcError(".%s is not allowed; string methods are: %s"
@@ -133,6 +198,8 @@ def compile_expr(expr: str, fields):
             return row.get(n.id if n.id in fields else lookup[n.id.lower()])
         if t is ast.BinOp:
             a, b = ev(n.left, row), ev(n.right, row)
+            if a is None or b is None:
+                return None
             if isinstance(n.op, ast.Pow) and isinstance(b, (int, float)) and abs(b) > _MAX_POW:
                 raise CalcError("An exponent over %d is refused." % _MAX_POW)
             if isinstance(n.op, ast.Mult) and (isinstance(a, str) or isinstance(b, str)):
@@ -141,7 +208,10 @@ def compile_expr(expr: str, fields):
                     raise CalcError("That would make a string over %d characters." % _MAX_LEN)
             return _BIN[type(n.op)](a, b)
         if t is ast.UnaryOp:
-            return _UN[type(n.op)](ev(n.operand, row))
+            v = ev(n.operand, row)
+            if v is None and not isinstance(n.op, ast.Not):
+                return None
+            return _UN[type(n.op)](v)
         if t is ast.BoolOp:
             if isinstance(n.op, ast.And):
                 v = True
@@ -160,6 +230,10 @@ def compile_expr(expr: str, fields):
             left = ev(n.left, row)
             for op, c in zip(n.ops, n.comparators):
                 right = ev(c, row)
+                #  Only ==, != and `is` have an answer about a null; anything else is false.
+                if (left is None or right is None) and not isinstance(
+                        op, (ast.Eq, ast.NotEq, ast.Is, ast.IsNot)):
+                    return False
                 if not _CMP[type(op)](left, right):
                     return False
                 left = right
@@ -169,6 +243,8 @@ def compile_expr(expr: str, fields):
         if t is ast.Call:
             if isinstance(n.func, ast.Attribute):
                 obj = ev(n.func.value, row)
+                if obj is None:
+                    return None
                 if not isinstance(obj, str):
                     raise CalcError(".%s() needs text, and this row has %r"
                                     % (n.func.attr, obj))
@@ -178,11 +254,25 @@ def compile_expr(expr: str, fields):
                         isinstance(a, int) and a > _MAX_LEN for a in args):
                     raise CalcError("A width over %d is refused." % _MAX_LEN)
                 return getattr(obj, n.func.attr)(*args)
-            return FUNCS[n.func.id](*[ev(a, row) for a in n.args])
+            fname = n.func.id
+            if fname == "iif":
+                if len(n.args) != 3:
+                    raise CalcError("iif() takes three values: iif(test, a, b).")
+                return ev(n.args[1], row) if ev(n.args[0], row) else ev(n.args[2], row)
+            args = [ev(a, row) for a in n.args]
+            if fname in _NULL_SAFE and any(a is None for a in args):
+                return None
+            if fname in ("upper", "lower", "trim"):
+                if len(args) != 1:
+                    raise CalcError("%s() takes one value." % fname)
+                return FUNCS[fname](str(args[0]))
+            return FUNCS[fname](*args)
         if t is ast.Attribute:
             raise CalcError(".%s must be called, as .%s()" % (n.attr, n.attr))
         if t is ast.Subscript:
             obj = ev(n.value, row)
+            if obj is None:
+                return None
             s = n.slice
             if type(s) is ast.Slice:
                 return obj[slice(*(ev(x, row) if x is not None else None
@@ -191,9 +281,16 @@ def compile_expr(expr: str, fields):
         if t is ast.Tuple:
             return tuple(ev(x, row) for x in n.elts)
         if t is ast.JoinedStr:
-            return "".join(str(ev(v, row)) for v in n.values)
+            #  A null anywhere makes the whole string null, as text concatenation does in a
+            #  database, rather than writing the word "None" into somebody's labels.
+            parts = [ev(v, row) for v in n.values]
+            if any(p is None for p in parts):
+                return None
+            return "".join(str(p) for p in parts)
         if t is ast.FormattedValue:
             v = ev(n.value, row)
+            if v is None:
+                return None
             spec = ev(n.format_spec, row) if n.format_spec is not None else ""
             if any(int(d) > _MAX_LEN for d in re.findall(r"\d+", spec)):
                 raise CalcError("A width over %d is refused." % _MAX_LEN)

{env_able-2.0.1 → env_able-2.1.0}/src/env_able/atlas/docs/atlas-guide.md

@@ -245,6 +245,11 @@ Draw order, top to bottom — drag to reorder. Each row has:
 
 **Right-clicking the row opens that same menu.** Either gesture, same menu.
 
+**Duplicate**, in that menu, copies the layer as it is now, unsaved edits included, as
+"*name* copy", then "*name* copy (2)". It keeps the look and filter and takes a colour of its own,
+and an edit to one does not reach the other. Nothing is written to disk: a save keeps the copy in
+the project, and Morph or Save As makes a file of it. **Undo** takes it away again.
+
 A **bar beside the *Layers* heading** runs while geometry is coming in — opening a project, a
 layer arriving, or the full-resolution swap a layout asks for. Hover it and it says what it is
 waiting for. Indeterminate, because none of that reports progress.
@@ -642,8 +647,8 @@ from 339.8 MB to 53.6 MB. A narrower layer is sent exactly as before.
 The colour chip on a layer row opens the picker. For polygons it has **Fill** and **Outline**
 tabs.
 
-**A layer's look travels.** Right-click ▸ **Save style** writes it as an `.atlasstyle` file —
-colour, outline, opacity, symbology, labels, without the data — and **Apply style…** puts one on
+**A layer's look travels.** Right-click ▸ **Save Style** writes it as an `.atlasstyle` file —
+colour, outline, opacity, symbology, labels, without the data — and **Apply Style…** puts one on
 another layer; the *Symbology* tab's **Styles** group does the same for the layer picked there.
 That is how a client's operator colours carry from one map to the next: the same
 operator takes the same colour. Field names are matched against the new layer's own columns, as
@@ -845,9 +850,9 @@ picked in that tab: a label field (or *No labels*), **View Unplaced**, and **Con
 drawn whatever collides. It is how one label is moved or reworded for print without touching the
 data. The source layer stops labelling, so nothing prints twice; `Ctrl+Z` puts it back.
 
-### Hex bins
+### Hex Bins
 
-**Right-click a point layer ▸ Hex bins** counts its points in hexagons and colours each by how many
+**Right-click a point layer ▸ Hex Bins** counts its points in hexagons and colours each by how many
 it holds — a new layer, in natural-breaks classes, drawn just above the points, which are hidden
 underneath. At basin scale 30,000 laterals print as solid colour and a heatmap has no legend a
 reader can look a number up in; bins have both. Cells are about 40 across the data by default,
@@ -871,14 +876,32 @@ Across the top, as in ArcGIS Pro:
 | **Add Field** | Opens Fields with the new-field row ready |
 | **Calculate** | Calculate Field (below) |
 
+**Click a row to select its feature**, as in Pro: **Ctrl+click** adds or removes one row and
+**Shift+click** selects the run from the last row clicked, in the order the table shows. The
+map draws the selection at once.
+
 ### Calculate Field
 
 Pick a field and write an expression, ArcGIS Pro's way: a field is `!NAME!` (click a field
-under the box to insert it). Arithmetic, comparisons, `a if test else b`, f-strings, text
-methods (`.upper()`, `.lower()`, `.title()`, `.strip()`, `.replace()`, `.zfill()` and a few
-more) and `abs`, `round`, `min`, `max`, `len`, `str`, `int`, `float`, `sqrt`, `floor`, `ceil`,
-`log`, `log10`, `exp` are available. Nothing else: an expression cannot import, open files or
-reach anything that is not the row's values.
+under the box to insert it), and ArcMap's `[NAME]` works too. Arithmetic, comparisons,
+`a if test else b`, f-strings, text methods (`.upper()`, `.lower()`, `.title()`, `.strip()`,
+`.replace()`, `.zfill()` and a few more) and `abs`, `round`, `min`, `max`, `len`, `str`, `int`,
+`float`, `bool`, `sqrt`, `floor`, `ceil`, `log`, `log10`, `exp`, `iif`, `upper`, `lower`, `trim` are
+available. `iif(test, a, b)` only works out the side it takes, so
+`iif(!N! != 0, 100 / !N!, 0)` never divides by zero. Nothing else: an expression cannot import,
+open files or reach anything that is not the row's values.
+
+**Suggestions** appear as you type: a few letters offer the functions and fields that start
+with them, `!` or `[` offers the fields, and a `.` after a value offers the text methods. **Tab**
+or **Enter** takes the highlighted one, the arrow keys move, **Esc** closes the list.
+
+**A blank value stays blank.** `!EUR! * 1000` on a row with no EUR gives no value rather than
+stopping the calculation, a comparison with a blank is false, and an f-string with a blank in it
+is blank.
+
+**A new field**: choose **+ New field…** at the bottom of the field list, name it and pick its
+type, or *Type from the result* to have Atlas work the type out from what the expression gives.
+The field is created as part of the same edit, so one Undo takes the column away again.
 
 With a selection it calculates **only the selected records**, and says so; otherwise all of
 them. **Preview** shows the first five results without changing anything. Every row is checked
@@ -898,9 +921,45 @@ Edits are **staged**, not written. The count of unsaved changes is shown, and:
 
 - **Save** writes back to the source file (only offered when there is a file to write to)
 - **Save As** writes a new GeoPackage
-- **Undo** / **Discard** roll back
+- **Undo** / **Redo** / **Discard** roll back, and forward again. Redo is offered until the
+  next new edit
 - **Restore** recovers from the backup Atlas takes before its first write
 
+### Edit Vertices
+
+**Tools ▸ Edit ▸ Vertices** reshapes features. A panel opens at the top right of the map: pick the
+layer, then click a feature. With one feature already selected, the tool opens on it, as Pro's
+does. The feature's vertices show as white handles with a smaller handle at the middle of each
+edge. Then:
+
+| To | Do |
+|---|---|
+| move a vertex | drag it |
+| add a vertex | drag an edge's middle handle |
+| delete a vertex | click it, then **Delete Vertex** or the **Delete** key |
+| undo, redo | the panel's arrows, or **Ctrl+Z** / **Ctrl+Y** |
+| put it all back | **Discard**, after a confirm: the shape edits on this layer go, attribute edits stay |
+| stop editing | **✕** at the top right, or **Esc**. Unsaved edits are kept, to save or undo later |
+
+**Snapping** lands a dragged vertex on another feature's vertex, or failing that on its nearest
+line, within 12 pixels. Both are on by default and toggle in the panel. It snaps to the real
+vertex even where the map is drawing a simplified copy of a large layer.
+
+Every change is a staged edit, like a cell edit, so the attribute table's Undo, Save and Discard
+cover it too. A change that would make a polygon cross itself is refused with the reason, a ring
+keeps three corners and a line two, and a point can only move. **Save** writes to the layer's
+file after a backup; on a layer with no file (a drawn AOI, a query result) it keeps the edits in
+the project instead. A format that stores no geometry (CSV, Excel) cannot be reshaped: Save As a
+GeoPackage first.
+
+### Layer Properties
+
+**Right-click a layer ▸ Properties** shows where it came from and what it is, as Pro's Layer
+Properties ▸ Source does: the file, feature class, format, size and date; the coordinate system
+the file is in, beside the one Atlas holds it in (WGS 84) and draws it in (Web Mercator); the
+feature count, geometry types, vertices and extent; and every field with its type and how many
+are blank. A layer with no file says so.
+
 ### Layers with no file behind them
 
 A layer pulled from Databricks is a **query result**, not a file — there is nothing to write
@@ -926,6 +985,7 @@ rather than failing silently.
 | **Near** | How far is every feature from the nearest feature of another layer: adds a `dist_<layer>_<unit>` column, empty past an optional limit |
 | **Erase** | This layer, with another layer's polygons cut out of it. Clip's opposite |
 | **Simplify** | Lines and polygons with fewer vertices, none moved more than the tolerance; points are refused |
+| **Summary Statistics** | Totals, averages and counts for each group, as a **table** in the Tables panel, not a layer |
 
 **History** (beside the tools) lists this session's runs, newest first. Picking one opens its tool
 with the same settings filled in and stops, so you can check them before pressing Run.
@@ -983,6 +1043,20 @@ Matches `arcpy.management.Dissolve`.
   end to end and gives each run its own feature, so two unconnected roads called "Main" stay
   two features.
 
+### Summary Statistics
+
+Matches `arcpy.analysis.Statistics`. The input is a layer or a table, and the output is a
+**table**: it lands in the Tables panel, since it has no shapes to draw.
+
+- **Group By** — the fields that split the rows into groups, picked as Dissolve's fields are.
+  Tick none, *(Nothing)*, for a single row covering everything. A blank in a Group By field is a
+  group of its own, and the result says how many rows it holds.
+- **Statistics** — field + statistic pairs: Dissolve's thirteen plus `MODE`, the commonest value
+  (the lowest, on a tie). A text field is offered only what Pro allows text: `MIN`, `MAX`,
+  `COUNT`, `FIRST`, `LAST`, `UNIQUE`, `CONCATENATE`, `MODE`.
+- Columns are named `SUM_EUR`, `MODE_OPERATOR` and so on. Blanks are left out of every statistic,
+  and there is no `FREQUENCY` column: `COUNT` on a field with no blanks counts each group's rows.
+
 ---
 
 ## The Catalog pane
@@ -1021,6 +1095,10 @@ A container offers what you can **create** in it. An item offers what you can **
 | a map | Open, Rename…, Delete Map |
 | a layout | Open, Rename…, Delete Layout |
 | a feature class or dataset | Add To Current Map, Copy Path |
+
+**A click selects a dataset; a double-click adds it to the map**, as do dragging it onto the map
+and *Add To Current Map*. A single click used to add it, which put layers on the map that nobody
+meant to add.
 | a geodatabase or folder | Add All Layers To Map, Copy Path, Refresh, Remove From Project |
 
 An **empty geodatabase registers**. Registering is not loading, and a `.gdb` you point Atlas at

{env_able-2.0.1 → env_able-2.1.0}/src/env_able/atlas/docs/env-able-library.md

@@ -280,6 +280,16 @@ Fewer vertices on lines and polygons, no edge moved more than `tolerance`, measu
 so the distance is true on the ground. Topology is preserved. Points are refused, and the result's
 warnings say how many vertices went.
 
+### `env.SummaryStatistics(table, statistics_fields, case_field=None, output=None, separator=", ")`
+
+ArcGIS Pro's Summary Statistics: one row per unique set of `case_field` values, with each
+statistic asked for, as a **table** with no geometry. `table` is a path, a DataFrame or a
+GeoDataFrame, whose geometry is ignored. `statistics_fields` is `[[field, statistic], ...]`, for
+example `[["EUR", "SUM"], ["OPERATOR", "MODE"]]`; the statistics are `SUMMARY_STATISTICS`
+(Dissolve's plus `MODE`), and a text field takes only `SUMMARY_TEXT_STATISTICS`. Leave
+`case_field` out for one row. Columns are named `SUM_EUR`; blanks are left out of every statistic,
+and a blank case value is a group of its own, counted in the warnings.
+
 ---
 
 ## Pipelines and async
@@ -563,7 +573,7 @@ draws no text at all with no error.
 `rest_external_links_frames`, `connector_arrow_frames`
 
 **Geoprocessing** — `Clip`, `Buffer`, `Intersect`, `Union`, `Dissolve`, `SpatialJoin`, `Near`,
-`Erase`, `Simplify`, plus `*_async` for each, `SJ_MATCH`
+`Erase`, `Simplify`, `SummaryStatistics`, plus `*_async` for each, `SJ_MATCH`
 
 **Pipeline** — `load` → `SpatialPipeline` → `.run()` / `.run_async()`