Cycles-utils 4.0.0__tar.gz → 4.0.2__tar.gz

{cycles_utils-4.0.0 → cycles_utils-4.0.2}/Cycles_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Cycles-utils
-Version: 4.0.0
+Version: 4.0.2
 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
@@ -42,6 +42,7 @@ Dynamic: summary
 This package provides a number of tools for users to prepare Cycles simulation input files, run Cycles simulations, and post-process Cycles simulation results.
 
 For usage examples, please refer to this [Jupyter notebook](https://github.com/PSUmodeling/Cycles/blob/master/cycles-utils.ipynb).
+For more complex usage examples, please refer to this [Colab notebook](https://colab.research.google.com/drive/1d8TFfZR_t6eo-Lgh8ZdR382RUcAXlawf?usp=sharing).
 
 # Installation
 

{cycles_utils-4.0.0 → cycles_utils-4.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Cycles-utils
-Version: 4.0.0
+Version: 4.0.2
 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
@@ -42,6 +42,7 @@ Dynamic: summary
 This package provides a number of tools for users to prepare Cycles simulation input files, run Cycles simulations, and post-process Cycles simulation results.
 
 For usage examples, please refer to this [Jupyter notebook](https://github.com/PSUmodeling/Cycles/blob/master/cycles-utils.ipynb).
+For more complex usage examples, please refer to this [Colab notebook](https://colab.research.google.com/drive/1d8TFfZR_t6eo-Lgh8ZdR382RUcAXlawf?usp=sharing).
 
 # Installation
 

{cycles_utils-4.0.0 → cycles_utils-4.0.2}/README.md

@@ -4,6 +4,7 @@
 This package provides a number of tools for users to prepare Cycles simulation input files, run Cycles simulations, and post-process Cycles simulation results.
 
 For usage examples, please refer to this [Jupyter notebook](https://github.com/PSUmodeling/Cycles/blob/master/cycles-utils.ipynb).
+For more complex usage examples, please refer to this [Colab notebook](https://colab.research.google.com/drive/1d8TFfZR_t6eo-Lgh8ZdR382RUcAXlawf?usp=sharing).
 
 # Installation
 

{cycles_utils-4.0.0 → cycles_utils-4.0.2}/cycles/cycles.py

@@ -150,7 +150,7 @@ class Cycles:
         return _plot_yield(self.output['harvest'].data, ax=ax, fontsize=fontsize)
 
 
-    def plot_operations(self, rotation_size: int | None=None, *, axs: Axes | np.ndarray | None=None, fontsize: int | None=None):
+    def plot_operations(self, *, axs: Axes | np.ndarray | None=None, fontsize: int | None=None):
         """Plot operation timelines grouped by rotation year.
 
         Args:
@@ -167,7 +167,6 @@ class Cycles:
         assert self.control is not None
         assert self.operations is not None
 
-        if rotation_size is None:
-            rotation_size = self.control.simulation_years.rotation_size
+        rotation_size = self.control.simulation_years.rotation_size
 
         return _plot_operations(self.operations, rotation_size, axs=axs, fontsize=fontsize)

{cycles_utils-4.0.0 → cycles_utils-4.0.2}/cycles/cycles_tools/_base_file.py

@@ -42,6 +42,6 @@ def parse_value(raw: str, name: str, hint: type) -> int | float | str:
 
 def unwrap_optional(t) -> type:
     origin = getattr(t, '__origin__', None)
-    if origin is Union or origin is types.UnionType:
+    if origin is Union or origin is types.UnionType or isinstance(t, types.UnionType):
         return next(arg for arg in t.__args__ if arg is not type(None))
     return t

{cycles_utils-4.0.0 → cycles_utils-4.0.2}/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.0 → cycles_utils-4.0.2}/cycles/cycles_tools/plot_tools.py

@@ -150,30 +150,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)

{cycles_utils-4.0.0 → cycles_utils-4.0.2}/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,11 +69,29 @@ 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.
@@ -86,10 +108,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 +133,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 +178,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 +212,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 +230,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 +259,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 +275,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 +291,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.0 → cycles_utils-4.0.2}/setup.py

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