Cycles-utils 4.0.1__tar.gz → 4.0.3__tar.gz

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/Cycles_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Cycles-utils
-Version: 4.0.1
+Version: 4.0.3
 Summary: Python scripts to build Cycles input files and post-process Cycles output files
 Home-page: https://github.com/PSUmodeling/Cycles-utils
 Author: Yuning Shi

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Cycles-utils
-Version: 4.0.1
+Version: 4.0.3
 Summary: Python scripts to build Cycles input files and post-process Cycles output files
 Home-page: https://github.com/PSUmodeling/Cycles-utils
 Author: Yuning Shi

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/__init__.py

@@ -12,6 +12,7 @@ from .cycles_tools import SoilLayer
 from .cycles_tools import plot_yield
 from .cycles_tools import plot_operations
 from .cycles_tools import plot_map
+from .cycles_tools import plot_satellite_map
 from .cycles_tools import Operation, Planting, Tillage, Harvest, Kill, FixedFertilization, FixedIrrigation, AutoIrrigation
 from .cycles_runner import CyclesRunner
 from .rotation_builder import CyclesRotationBuilder, Crop, CropGroup

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/cycles.py

@@ -5,7 +5,6 @@ import pandas as pd
 import subprocess
 from collections.abc import Collection
 from dataclasses import dataclass, field
-from datetime import datetime
 from pathlib import Path
 from matplotlib.axes import Axes
 from .cycles_tools import SoilLayer, ControlConfig
@@ -27,8 +26,8 @@ class Output:
 class Cycles:
     """Interface for executing one Cycles simulation and reading its files.
 
-    Provides methods to run simulations, read outputs, and inspect soil/weather/operation
-    configurations. Automatically loads the control file upon initialization.
+    Provides methods to run simulations, read outputs, and inspect soil/weather/operation configurations. Automatically
+    loads the control file upon initialization.
 
     Attributes:
         path: Path to the simulation directory (containing input/ and output/ subdirs).

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/cycles_runner.py

@@ -29,9 +29,8 @@ class SimulationContext:
 class CyclesRunner:
     """Run one or many Cycles simulations with templated inputs.
 
-    Manages batch execution of Cycles simulations by generating control files,
-    operation files, and nudge files from templates and parameter dictionaries.
-    Consolidates results into a summary CSV file.
+    Manages batch execution of Cycles simulations by generating control files, operation files, and nudge files from
+    templates and parameter dictionaries.  Consolidates results into a summary CSV file.
 
     Attributes:
         executable: Absolute path to the Cycles executable binary.
@@ -110,7 +109,6 @@ class CyclesRunner:
 
 
     def _resolve(self, simulation: dict[str, Any], control_dict: dict[str, Any], operation_dict: dict[str, Any] | None, calibration_dict: dict[str, Any] | None) -> SimulationContext:
-        """Call control_dict once per row and resolve all derived values."""
         control = resolve_dict_values(control_dict, simulation)
         return SimulationContext(
             name=control['simulation_name'],

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/cycles_tools/__init__.py

@@ -9,13 +9,12 @@ from .soil_file import MAPPABLE_PARAMETERS
 from .soil_file import SoilLayer
 from .soil_file import generate_soil_file
 from .soil_file import read_soil_file
-from .soil_file import map_to_dataframe
-from .soil_file import from_dataframe
 from .weather_file import read_weather_file
 from .reinit_file import generate_reinit_file
 from .plot_tools import plot_yield
 from .plot_tools import plot_operations
 from .plot_tools import plot_map
+from .plot_tools import plot_satellite_map
 from ._base_file import resolve_dict_values
 
 __all__ = [
@@ -31,4 +30,5 @@ __all__ = [
     "plot_yield",
     "plot_operations",
     "plot_map",
+    "plot_satellite_map",
 ]

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/cycles_tools/_base_file.py

@@ -23,7 +23,7 @@ def write_file(fn: Path, config) -> None:
 
 
 def resolve_dict_values(user_dict: dict, simulation: dict[str, Any] | None) -> dict:
-    return {key: func(simulation) if callable(func) else func for key, func in user_dict.items()}
+    return {key.lower(): func(simulation) if callable(func) else func for key, func in user_dict.items()}
 
 
 def extract(dc_class, resolved: dict) -> dict:

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/cycles_tools/control_file.py

@@ -78,6 +78,35 @@ def _get_soil_layers(fn: Path) -> int:
 def generate_control_file(fn: str | Path, user_dict: dict, *, simulation_dict: dict[str, Any] | None=None) -> ControlConfig:
     """Generate and write a Cycles control file.
 
+    Provide either direct values or callables that accept a simulation row and return a value in `user_dict`. The
+    parameter names should be in lowercase and correspond to the fields in Cycles simulation control files. If a field
+    is not provided, it will be filled with a default value. If a field's value is a callable, it will be called with
+    the `simulation_dict` to resolve its value.
+
+    The following fields are required in `user_dict`:
+
+      - `simulation_start_year`
+      - `simulation_end_year`
+      - `rotation_size`
+      - `operation_file`
+      - `soil_file`
+      - `weather_file`
+
+    The default values for other fields are:
+
+      - `crop_file`: `GenericCrops.crop`
+      - `reinit_file`: `N/A`
+      - `soil_layers`: inferred from the soil file (if not provided)
+      - `co2_level`: `-999`
+      - `use_reinitialization`: `0`
+      - `adjusted_yields`: `0`
+      - `hydrology_option`: `1`
+      - `automatic_nitrogen`: `0`
+      - `automatic_phosphorus`: `0`
+      - `automatic_sulfur`: `0`
+
+    All output control fields default to `0`.
+
     Args:
         fn: Destination control file path.
         user_dict: Values or callables for control fields.

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/cycles_tools/nudge_file.py

@@ -45,6 +45,14 @@ def _build_nudge_config(user_dict: dict, simulation_dict: dict[str, Any] | None)
 def generate_nudge_file(fn: str | Path, user_dict: dict, *, simulation_dict: dict[str, Any] | None=None) -> None:
     """Write a Cycles nudge file from user-provided values.
 
+    Provide either direct values or callables that accept a simulation row and return a value in `user_dict`. The
+    parameter names should be in lowercase and correspond to the fields in Cycles nudge (calibration) files. If a field
+    is not provided, it will be filled with a default value. If a field's value is a callable, it will be called with
+    the `simulation_dict` to resolve its value.
+
+    The default values for all calibration multipliers are `1.0`, and the default values for `kd_no3` and `kd_nh4` are
+    `0.0` and `5.6`, respectively.
+
     Args:
         fn: Destination nudge file path.
         user_dict: Values or callables for nudge parameters.

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/cycles_tools/operation_file.py

@@ -8,6 +8,7 @@ class Operation(Protocol):
     year: int | None
     doy: int
     relative_doy: bool
+    resolved_doy: int | None
 
 @dataclass(kw_only=True)
 class Planting(Operation):
@@ -33,6 +34,7 @@ class Planting(Operation):
     harvest_timing: float = -999
     kill_after_harvest: int = 1
     relative_doy: bool = field(default=False, metadata={'readable': False})
+    resolved_doy: int | None = field(default=None, metadata={'readable': False})
 
 @dataclass(kw_only=True)
 class Tillage(Operation):
@@ -43,6 +45,7 @@ class Tillage(Operation):
     frac_thermal_time: float = 0.0
     kill_efficiency: float = 0.0
     relative_doy: bool = field(default=False, metadata={'readable': False})
+    resolved_doy: int | None = field(default=None, metadata={'readable': False})
 
 @dataclass(kw_only=True)
 class Harvest(Operation):
@@ -53,6 +56,7 @@ class Harvest(Operation):
     frac_thermal_time: float = 0.0
     kill_efficiency: float = 0.0
     relative_doy: bool = field(default=False, metadata={'readable': False})
+    resolved_doy: int | None = field(default=None, metadata={'readable': False})
 
 @dataclass(kw_only=True)
 class Kill(Operation):
@@ -63,6 +67,7 @@ class Kill(Operation):
     frac_thermal_time: float = 0.0
     kill_efficiency: float = 0.0
     relative_doy: bool = field(default=False, metadata={'readable': False})
+    resolved_doy: int | None = field(default=None, metadata={'readable': False})
 
 @dataclass(kw_only=True)
 class FixedFertilization(Operation):
@@ -74,6 +79,7 @@ class FixedFertilization(Operation):
     method: str = 'Broadcast'
     depth: float = 0.0
     relative_doy: bool = field(default=False, metadata={'readable': False})
+    resolved_doy: int | None = field(default=None, metadata={'readable': False})
 
 @dataclass(kw_only=True)
 class FixedIrrigation(Operation):
@@ -81,6 +87,7 @@ class FixedIrrigation(Operation):
     doy: int
     volume: float = 0.0
     relative_doy: bool = field(default=False, metadata={'readable': False})
+    resolved_doy: int | None = field(default=None, metadata={'readable': False})
 
 @dataclass(kw_only=True)
 class AutoIrrigation:
@@ -99,6 +106,13 @@ OPERATION_PARAMETERS = {
 }
 
 
+def _resolve_reference_doy(operations: list[Operation], relative_doy: int) -> int:
+    planting = next((op for op in reversed(operations) if isinstance(op, Planting)), None)
+    if planting is None:
+        raise ValueError("Relative DOY specified but no planting operation found.")
+    return planting.doy + relative_doy
+
+
 def read_operation_file(operation: str | Path) -> list:
     """Parse a Cycles operation file into operation objects.
 
@@ -137,6 +151,7 @@ def read_operation_file(operation: str | Path) -> list:
             if isinstance(raw_doy, str) and raw_doy.split()[1].strip().startswith('+'):
                 operation_dict['doy'] = int(raw_doy.split()[1].strip()[1:])
                 operation_dict['relative_doy'] = True
+                operation_dict['resolved_doy'] = _resolve_reference_doy(operations, operation_dict['doy'])
             else:
                 operation_dict['doy'] = parse_value(raw_doy, 'doy', hints['doy'])
                 operation_dict['relative_doy'] = False

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/cycles_tools/output_file.py

@@ -15,7 +15,7 @@ def _parse_units(lines: list[str], columns) -> dict[str, str]:
 
 
 def read_output(path: str | Path, output_type: str) -> tuple[pd.DataFrame, dict[str, str]]:
-    """Read one Cycles output table and associated unit strings.
+    """Read one Cycles output file and associated unit strings.
 
     Args:
         path: Directory containing output CSV files.

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/cycles_tools/plot_tools.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 import cartopy.crs as ccrs
 import cartopy.feature as feature
+import cartopy.io.img_tiles as cimgt
 import geopandas as gpd
+import math
 import matplotlib.lines as mlines
 import matplotlib.pyplot as plt
 import numpy as np
@@ -150,30 +152,34 @@ def plot_operations(operations: list, rotation_size: int, *, axs: Axes | np.ndar
         for key, value in OPERATION_TYPES.items():
             sub_list = [op for op in operations if type(op).__name__.lower() == key and op.year == y + 1]
 
-            if len(sub_list) == 0: continue
+            if not sub_list: continue
 
             axs[y].plot(
-                [op.doy for op in sub_list], [value.yloc] * len(sub_list),
+                [op.doy if not op.relative_doy else op.resolved_doy for op in sub_list], [value.yloc] * len(sub_list),
                 'o',
-                label=value.title + ':\n' + '\n'.join(f'{op.doy}: {getattr(op, value.label)}' if value.label is not None else f'{op.doy}' for op in sub_list),
+                label=value.title + ':\n' + '\n'.join(f'{op.doy if not op.relative_doy else op.resolved_doy}: {getattr(op, value.label)}' if value.label is not None else f'{op.doy}' for op in sub_list),
                 color=value.color,
                 ms=10,
             )
 
+            if key == 'planting':
+                for op in sub_list:
+                    if op.end_doy == -999: continue
+                    axs[y].fill_betweenx([value.yloc - 0.5, value.yloc + 0.5], op.doy, op.end_doy, alpha=0.25, color=value.color)
+
         axs[y].set_xlim(-1, 370)
         axs[y].grid(False)
-        axs[y].spines['right'].set_color('none')
-        axs[y].spines['left'].set_color('none')
         axs[y].yaxis.set_ticks_position('none')
         axs[y].yaxis.set_tick_params(left=False, right=False, which='both', labelleft=False)
         axs[y].set_ylim(-3, 7)
         axs[y].text(184, 5, f'Year {y + 1}', ha='center')
+        for spine in ('right', 'left', 'top'):
+            axs[y].spines[spine].set_color('none')
 
         # set the y-spine
         axs[y].spines['bottom'].set_position('zero')
 
         # turn off the top spine/ticks
-        axs[y].spines['top'].set_color('none')
         axs[y].xaxis.tick_bottom()
         axs[y].set_xticks(MDOYS)
         axs[y].set_xticklabels(MONTHS)
@@ -270,3 +276,48 @@ def plot_map(gdf: gpd.GeoDataFrame, column: str, *, projection: ccrs.Projection=
         ax.set_title(title) # type: ignore
 
     return fig, ax  # type: ignore
+
+
+def _zoom_from_extent(extent, *, desired_pixels: int=1024) -> int:
+    """Determine the appropriate zoom level for a given map extent.
+    Number of global tiles at each zoom level is 2 ^ zoom_level
+    """
+    PIXELS_PER_TILE = 256
+
+    dx = abs(extent[1] - extent[0])
+    dy = abs(extent[3] - extent[2])
+
+    return round(max(math.log(desired_pixels / PIXELS_PER_TILE * 180 / dy) / math.log(2), math.log(desired_pixels / PIXELS_PER_TILE * 360 / dx) / math.log(2)))
+
+
+def plot_satellite_map(fig: Figure, extent: tuple[float, float, float, float], *,
+    alpha: float=1.0, ax: tuple[float, float, float, float] | None=None, desired_pixels: int=1024, style: str | None=None) -> tuple[GeoAxes, ccrs.Projection]:
+    """Render a satellite basemap over a geographic extent.
+
+    Args:
+        fig: Matplotlib figure used to create the map axes.
+        extent: Geographic bounds as ``(west, east, south, north)`` in degrees.
+        alpha: Basemap transparency where ``1.0`` is fully opaque.
+        ax: Optional axes rectangle passed to ``Figure.add_axes``.  If omitted, a full-figure subplot is created.
+        desired_pixels: Target figure resolution in pixels used to estimate tile zoom.
+        style: Optional Cartopy GoogleTiles style string. If omitted, ArcGIS World Imagery tiles are used.
+
+    Returns:
+        Tuple containing:
+            - GeoAxes with the satellite basemap.
+            - Projection associated with the tile source.
+    """
+    GOOGLE_URL = 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}.jpg'
+
+    google_satellite = cimgt.GoogleTiles(url=GOOGLE_URL) if style is None else cimgt.GoogleTiles(style=style)
+
+    if ax is None:
+        ax = fig.add_subplot(1, 1, 1, projection=google_satellite.crs)  # type: ignore
+    else:
+        ax = fig.add_axes(ax, projection=google_satellite.crs)  # type: ignore
+
+    assert isinstance(ax, GeoAxes)
+    ax.set_extent(extent, crs=ccrs.PlateCarree())
+    ax.add_image(google_satellite, _zoom_from_extent(extent, desired_pixels=desired_pixels), alpha=alpha)
+
+    return ax, google_satellite.crs

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/cycles_tools/reinit_file.py

@@ -74,12 +74,12 @@ def _format_reinit_block(row: pd.Series, doy: int, n_layers: int) -> list[str]:
 
 
 def generate_reinit_file(out_path: str | Path, in_path: str | Path, doy: int) -> None:
-    """Write a reinit file for all years at a selected day-of-year.
+    """Write a re-initialization file from Cycles output for all years at a selected day-of-year.
 
     Args:
-        out_path: Destination reinit file path.
-        in_path: Simulation output directory or stem used by ``read_output``.
-        doy: Day-of-year extracted from reinit output.
+        out_path: Destination re-initialization file path.
+        in_path: Simulation output directory that contains Cycles output files.
+        doy: Day-of-year extracted from re-initialization.
     """
     out_path = Path(out_path)
     in_path  = Path(in_path)

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/cycles_tools/soil_file.py

@@ -215,50 +215,18 @@ def _parse_token(token: str, param: SoilParameter) -> str | int | float | None:
     return token
 
 
-def _row_to_layer(row: pd.Series) -> SoilLayer:
-    valid_fields = {f.name for f in fields(SoilLayer)}
-    kwargs = {col: (None if pd.isna(val) else val) for col, val in row.items() if col in valid_fields}
-    return SoilLayer(**kwargs)  # type: ignore
-
-
-def map_layers(profile: list[SoilLayer], target: list[SoilLayer]=DEFAULT_PROFILE, parameters: list[str]=MAPPABLE_PARAMETERS, soil_depth: float | None=None) -> list[SoilLayer]:
-    """Map measured soil properties onto a target profile.
-
-    The mapping is performed by overlap-weighted averaging for each requested
-    parameter, after trimming target layers to the effective profile depth.
-
-    Args:
-        profile: Soil profile layers in depth order.
-        target: Target layer structure to map onto.
-        parameters: Soil parameters to map from measured profile to target.
-        soil_depth: Optional maximum depth (m) to include in the mapped profile.
-
-    Returns:
-        A list of mapped soil layers aligned to the target profile.
-    """
+def _map_layers(profile: list[SoilLayer], target: list[SoilLayer]=DEFAULT_PROFILE, parameters: list[str]=MAPPABLE_PARAMETERS, soil_depth: float | None=None) -> list[SoilLayer]:
     trimmed = _trim(target, profile[-1].bottom, soil_depth)
     return [_map_layer(layer, profile, parameters) for layer in trimmed]
 
 
-def map_to_dataframe(layers: list[SoilLayer]) -> pd.DataFrame:
-    """Convert soil layers to a tabular representation.
-
-    Args:
-        layers: Soil layers to convert.
-
-    Returns:
-        A DataFrame with one row per layer, including computed ``thickness``.
-    """
-    return pd.DataFrame([{**asdict(layer), 'thickness': layer.thickness} for layer in layers])
-
-
 def generate_soil_file(fn: str | Path, profile: list[SoilLayer], *,
     target: list[SoilLayer]=DEFAULT_PROFILE, parameters: list[str]=MAPPABLE_PARAMETERS, soil_depth: float | None=None,
     desc: str='', slope: float | None=None, curve_number: float | None=None, hsg: str='') -> list[SoilLayer]:
-    """Map layers and write a Cycles-formatted soil file.
+    """Generate a Cycles-formatted soil file from a list of soil layers.
 
-    The input profile is first mapped to the target layering scheme, then
-    rendered to Cycles soil-file format and written to ``fn``.
+    The input profile is first mapped to the target layering scheme, then rendered to Cycles soil-file format and
+    written to ``fn``.
 
     Args:
         fn: Output soil file path.
@@ -279,7 +247,7 @@ def generate_soil_file(fn: str | Path, profile: list[SoilLayer], *,
     """
     if curve_number is not None and hsg:
         raise ValueError("Only one of curve_number and hsg can be provided.")
-    layers = map_layers(profile, target, parameters, soil_depth)
+    layers = _map_layers(profile, target, parameters, soil_depth)
     Path(fn).write_text('\n'.join(_render_soil_file(layers, desc, slope, curve_number, hsg)) + '\n')
     return layers
 
@@ -301,15 +269,3 @@ def read_soil_file(fn: str | Path) -> tuple[list[SoilLayer], dict]:
     meta, data_lines = _parse_header(lines)
     layers = _parse_layers(data_lines)
     return layers, meta
-
-
-def from_dataframe(df: pd.DataFrame) -> list[SoilLayer]:
-    """Convert a DataFrame into ``SoilLayer`` objects.
-
-    Args:
-        df: DataFrame containing columns matching ``SoilLayer`` fields.
-
-    Returns:
-        A list of ``SoilLayer`` instances created row-by-row.
-    """
-    return [_row_to_layer(row) for _, row in df.iterrows()]

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/gadm/__init__.py

@@ -7,7 +7,7 @@ from .gadm import county_fips
 from .gadm import county_gid
 from .gadm import county_name
 
-_all__ = [
+__all__ = [
     "read_gadm",
     "state_abbreviation",
     "state_fips",

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/rotation_builder.py

@@ -93,10 +93,9 @@ class RotationResult(NamedTuple):
 class CyclesRotationBuilder:
     """Run Cycles iteratively and append economically optimal operations.
 
-    Executes Cycles simulations for candidate crop-operation combinations,
-    selects the highest-return option at each break-point, and iteratively
-    builds a multi-year rotation. Integrates economic scoring with agronomic
-    constraints (e.g., minimum planting interval, crop group penalties).
+    Executes Cycles simulations for candidate crop-operation combinations, selects the highest-return option at each
+    break-point, and iteratively builds a multi-year rotation. Integrates economic scoring with agronomic constraints
+    (e.g., minimum planting interval, crop group penalties).
 
     Attributes:
         simulation: Base simulation name for generated input/output directories.

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/soilgrids/soilgrids.py

@@ -90,10 +90,8 @@ class SoilGrids:
         """Reproject loaded maps to a reference raster grid.
 
         Args:
-            reference_xds: Reference raster whose CRS, transform, and resolution
-                are used for reprojection.
-            reference_name: Column name used for the reference raster values in
-                the generated matched table.
+            reference_xds: Reference raster whose CRS, transform, and resolution are used for reprojection.
+            reference_name: Column name used for the reference raster values in the generated matched table.
             boundary: Boundary geometry used to clip all rasters after reprojection.
 
         Returns:
@@ -211,8 +209,8 @@ def download_soilgrids_data(path: str | Path, *,
     maps: list[str]=ALL_MAPS, boundary: Polygon | None=None, bbox: tuple[float, float, float, float] | None=None, crs: str='epsg:4326') -> None:
     """Download SoilGrids raster layers via WCS.
 
-    You can provide either a boundary polygon or an explicit bounding box.
-    Bounding boxes are expected in ``(west, south, east, north)`` order.
+    You can provide either a boundary polygon or an explicit bounding box.  Bounding boxes are expected in
+    ``(west, south, east, north)`` order.
 
     Args:
         path: Directory where downloaded GeoTIFF files are written.

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/cycles/ssurgo/ssurgo.py

@@ -1,8 +1,12 @@
 from __future__ import annotations
 import geopandas as gpd
+import matplotlib.colors as colors
+import matplotlib.pyplot as plt
+import numpy as np
 import pandas as pd
 import shapely
 from dataclasses import dataclass
+from matplotlib.axes import Axes
 from pathlib import Path
 from shapely.geometry import Point
 from cycles.cycles_tools import generate_soil_file as _generate_soil_file
@@ -65,12 +69,32 @@ SSURGO_PARAMETERS: dict[str, SsurgoParameter] = {
 
 LatLon = tuple[float, float]
 
+
+class MapUnitGeoDataFrame(gpd.GeoDataFrame):
+    def plot(self, **kwargs) -> Axes:
+        n = len(self)
+        kwargs.setdefault('column', 'musym')
+        kwargs.setdefault('legend', True)
+        kwargs.setdefault(
+            'cmap',
+            'tab20' if n > 20 else _truncate_colormap(plt.get_cmap('tab20'), 0, n / 20),
+        )
+        ax = super().plot(**kwargs)
+        ax.axis('off')
+        ax.set_aspect('equal')
+        return ax
+
+
 class Ssurgo:
     """Load SSURGO lookup tables and extract soil profiles for locations."""
 
     def __init__(self, path: str | Path, state: str, *, lat_lon: LatLon | None=None, boundary: gpd.GeoDataFrame | None=None) -> None:
         """Initialize SSURGO lookup tables and optional spatial subset.
 
+        When a location (`lat_lon`) or boundary polygon is provided, the map-unit table is filtered to include only
+        those map units that intersect the location or polygon; the map-units are also grouped by name and symbol, and
+        the major map unit is selected for profile extraction.
+
         Args:
             path: Directory containing SSURGO geodatabase and lookup CSV files.
             state: State identifier used in SSURGO file naming.
@@ -86,10 +110,10 @@ class Ssurgo:
         _validate_geographic_input(lat_lon, boundary)
 
         self.state: str = state
-        self._mapunits: gpd.GeoDataFrame | pd.DataFrame | None = None
-        self.grouped_mapunits: gpd.GeoDataFrame | pd.DataFrame | None = None
-        self.components: pd.DataFrame | None = None
-        self.horizons: pd.DataFrame | None = None
+        self._mapunits: gpd.GeoDataFrame | pd.DataFrame
+        self.components: pd.DataFrame
+        self.horizons: pd.DataFrame
+        self.grouped_mapunits: MapUnitGeoDataFrame | None = None
         self.mukey: int | None = None
         self.slope: float | None = None
         self.hsg: str = ''
@@ -111,21 +135,25 @@ class Ssurgo:
             )
         gdf = _read_mupolygon(path, state, boundary)
         self._mapunits = gdf.merge(luts['mapunit'], on='mukey', how='left')
-
         self.components = self.components[self.components['mukey'].isin(self._mapunits['mukey'].unique())]
         self.horizons = self.horizons[self.horizons['cokey'].isin(self.components['cokey'].unique())]
 
+        self._group_map_units()
+        self._select_major_mapunit()
         self._average_slope_hsg()
 
 
     @property
-    def mapunits(self) -> gpd.GeoDataFrame | pd.DataFrame | None:
+    def mapunits(self) -> MapUnitGeoDataFrame | pd.DataFrame:
         """Return loaded map-unit table.
 
         Returns:
             Map-unit table as GeoDataFrame/DataFrame, or None if not loaded.
         """
-        return self._mapunits
+        if isinstance(self._mapunits, gpd.GeoDataFrame):
+            return MapUnitGeoDataFrame(self._mapunits, geometry=self._mapunits.geometry.name, crs=self._mapunits.crs)
+        else:
+            return self._mapunits
 
 
     @property
@@ -152,39 +180,22 @@ class Ssurgo:
         return self._mapunits[self._mapunits['mukey'] == self.mukey]['musym'].iloc[0]
 
 
-    def group_map_units(self, *, geometry: bool=False) -> None:
-        """Group map units by base soil-series name.
-
-        Many map units share a base soil texture but differ in slope class or
-        minor qualifiers. This method groups by the base ``muname`` text before
-        the first comma and optionally dissolves geometries.
-
-        Args:
-            geometry: If True, dissolve polygons by grouped map-unit name.
-
-        Returns:
-            None.
-        """
-        if self.grouped_mapunits is not None:
-            return
-        assert self._mapunits is not None
-
+    def _group_map_units(self) -> None:
         gmu = self._mapunits.copy()
         gmu['muname'] = gmu['muname'].map(lambda name: name.split(',')[0])  # type: ignore
-        gmu['musym']  = gmu['musym'].map(_strip_slope_suffix)
+        gmu['musym'] = gmu['musym'].map(_strip_slope_suffix)
 
         mask = self.non_soil_mask(gmu)
         gmu.loc[mask, 'muname'] = 'Water, urban, etc.'
         gmu.loc[mask, 'mukey'] = -999
         gmu.loc[mask, 'musym'] = 'N/A'
 
-        if geometry:
-            gmu = gmu.dissolve(
-                by='muname',
-                aggfunc={'mukey': 'first', 'musym': 'first', 'shape_area': 'sum'},
-            ).reset_index() # type: ignore
+        gmu = gmu.dissolve(
+            by='muname',
+            aggfunc={'mukey': 'first', 'musym': 'first', 'shape_area': 'sum'},
+        ).reset_index() # type: ignore
 
-        self.grouped_mapunits = gmu
+        self.grouped_mapunits = MapUnitGeoDataFrame(gmu, geometry=gmu.geometry.name, crs=gmu.crs)
 
 
     def non_soil_mask(self, mapunits: pd.DataFrame | gpd.GeoDataFrame) -> pd.Series:
@@ -203,18 +214,8 @@ class Ssurgo:
         )
 
 
-    def select_major_mapunit(self) -> None:
-        """Select the dominant map unit by area.
-
-        Returns:
-            None.
-        """
-        if self.mukey is not None:
-            return
-        if self.grouped_mapunits is None:
-            self.group_map_units(geometry=True)
+    def _select_major_mapunit(self) -> None:
         assert self.grouped_mapunits is not None
-
         gdf = self.grouped_mapunits[~self.non_soil_mask(self.grouped_mapunits)].copy()
         gdf['area'] = gdf.area
         self.mukey  = int(gdf.loc[gdf['area'].idxmax(), 'mukey'])   # type: ignore
@@ -231,7 +232,6 @@ class Ssurgo:
             Soil profile as a list of ``SoilLayer`` records.
         """
         mukey = mukey or self._ensure_mukey()
-        assert self.components is not None and self.horizons is not None
 
         df = self.components[self.components['mukey'] == int(mukey)].copy()
         if major_only:
@@ -261,19 +261,15 @@ class Ssurgo:
         Returns:
             None.
         """
-        if mukey is None:
-            self.group_map_units(geometry=True)
-            self.select_major_mapunit()
-            mukey = self.mukey
-
-        assert mukey is not None
-        assert self._mapunits is not None
+        if mukey is not None:
+            hsg = self._mapunits[self._mapunits['mukey'] == mukey]['hydgrpdcd'].iloc[0] if hsg is None else hsg
+            slope = self._mapunits[self._mapunits['mukey'] == mukey]['slopegradwta'].iloc[0] if slope is None else slope
+        else:
+            mukey = self._ensure_mukey()
+            hsg = self.hsg if hsg is None else hsg
+            slope = self.slope if slope is None else slope
 
-        if hsg is None:
-            hsg = self._mapunits[self._mapunits['mukey'] == mukey]['hydgrpdcd'].iloc[0] if not self.hsg else self.hsg
-            assert hsg is not None
-        if slope is None:
-            slope = self._mapunits[self._mapunits['mukey'] == mukey]['slopegradwta'].iloc[0] if not self.slope else self.slope
+        assert mukey is not None and hsg is not None and slope is not None
 
         profile = self.get_soil_profile(mukey=mukey)
         desc = desc if desc is not None else _build_desc(self._get_muname(mukey), mukey, hsg)
@@ -281,20 +277,15 @@ class Ssurgo:
 
 
     def _ensure_mukey(self) -> int:
-        if self.mukey is None:
-            self.select_major_mapunit()
-        assert self.mukey is not None
+        assert self.mukey is not None, "A major soil map unit has not been selected, because a location or boundary has not been provided."
         return self.mukey
 
 
     def _get_muname(self, mukey: int) -> str:
-        assert self._mapunits is not None
         return self._mapunits[self._mapunits['mukey'] == mukey]['muname'].iloc[0]
 
 
     def _average_slope_hsg(self) -> None:
-        assert self._mapunits is not None
-
         gdf = self._mapunits[~self.non_soil_mask(self._mapunits)].copy()
         gdf['area'] = gdf.area
 
@@ -302,6 +293,13 @@ class Ssurgo:
         self.hsg = _dominant_hsg(gdf)   # type: ignore
 
 
+def _truncate_colormap(cmap, minval=0.0, maxval=1.0, n=100):
+    return colors.LinearSegmentedColormap.from_list(
+        'trunc({n},{a:.2f},{b:.2f})'.format(n=cmap.name, a=minval, b=maxval),
+        cmap(np.linspace(minval, maxval, n))
+    )
+
+
 def _validate_geographic_input(lat_lon: LatLon | None, boundary: gpd.GeoDataFrame | None) -> None:
     if lat_lon is not None and boundary is not None:
         raise ValueError("lat_lon and boundary are mutually exclusive — provide only one.")

{cycles_utils-4.0.1 → cycles_utils-4.0.3}/setup.py

@@ -5,7 +5,7 @@ with open('README.md', 'r') as f:
 
 setup(
     name='Cycles-utils',
-    version='4.0.1',
+    version='4.0.3',
     author='Yuning Shi',
     author_email="shiyuning@gmail.com",
     packages=find_packages(),