strategicc 2.2.0__tar.gz

strategicc-2.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shlhnj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

strategicc-2.2.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: strategicc
+Version: 2.2.0
+Summary: State and Transition Integrated Economic-Environmental Accounting
+Author: Shlhnj
+License: MIT License
+        
+        Copyright (c) 2026 Shlhnj
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/Shlhnj/strategicc
+Project-URL: Repository, https://github.com/Shlhnj/strategicc
+Project-URL: Issues, https://github.com/Shlhnj/strategicc/issues
+Keywords: STSM,land cover,ecosystem accounting,SEEA-EA,landscape ecology,Monte Carlo
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: Pillow>=10.0
+Requires-Dist: matplotlib>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# strategicc
+STRATEGICC: State and Transition Integrated Economic-Environmental Accounting
+
+A python package implementation of State-and-Transition Simulation Model (STSM) framework laid by Daniel et al (2016) (https://doi.org/10.1111/2041-210X.12597), integrated with the System of Economic-Environmental Accounting - Ecosystem Accounting (SEEA-EA) by United Nations (https://seea.un.org/ecosystem-accounting).
+
+## Usage
+### install the package
+```
+!pip install git+https://github.com/Shlhnj/strategicc.git
+```
+
+
+### Set Configuration
+
+```
+import strategicc.config as cfg
+from pathlib import Path
+
+cfg.LULC_PATH          = Path("2022.tif")
+cfg.STATE_CLASSES_CSV  = Path("25062026 State Class.csv")
+cfg.TRANSITIONS_CSV    = Path("23062026_stsm_transition_probabilities.csv")
+cfg.SPATIAL_MULT_CSV   = Path("27062026 Transition Spatial Multipliers.csv")
+cfg.TRANSITION_MULT_CSV= Path("27062026 Transition Multipliers.csv")
+cfg.MULT_DIR           = Path("mult_spat/")   #folder for transition spatial multiplier
+cfg.OUT_DIR            = Path("strategicc_test") #output folder
+
+
+cfg.ADJACENCY_STRENGTH   = 2
+cfg.START_YEAR           = 2022
+cfg.N_TIMESTEPS          = 30
+cfg.N_ITERATIONS         = 100    
+cfg.RNG_SEED             = 42
+
+cfg.USE_ADJACENCY        = True
+cfg.USE_SPATIAL_MULT     = True
+cfg.USE_TRANS_MULTIPLIER = True
+```
+
+### Diagnose Configuration
+
+```
+from strategicc import STSMEngine
+
+engine = STSMEngine.from_config()
+engine.load()
+engine.diagnostic()
+```
+
+### Run Engine
+
+```
+engine.run()
+```
+
+### Show Summary Plot
+
+```
+from strategicc import outputs
+
+summary_dir = engine.out_dir / "summary"
+
+print("Building summary tables...")
+area_df, trans_df = outputs.build_summary_tables(engine.iter_dirs, summary_dir)
+
+print("Plotting area envelope...")
+outputs.plot_area_envelope(area_df, engine.classes, summary_dir)
+
+print("Plotting transition envelope...")
+outputs.plot_transition_envelope(trans_df, summary_dir)
+
+Show plots inline
+from IPython.display import Image, display
+display(Image(str(summary_dir / "area_envelope.png")))
+display(Image(str(summary_dir / "transition_envelope.png")))
+```

strategicc-2.2.0/README.md

@@ -0,0 +1,75 @@
+# strategicc
+STRATEGICC: State and Transition Integrated Economic-Environmental Accounting
+
+A python package implementation of State-and-Transition Simulation Model (STSM) framework laid by Daniel et al (2016) (https://doi.org/10.1111/2041-210X.12597), integrated with the System of Economic-Environmental Accounting - Ecosystem Accounting (SEEA-EA) by United Nations (https://seea.un.org/ecosystem-accounting).
+
+## Usage
+### install the package
+```
+!pip install git+https://github.com/Shlhnj/strategicc.git
+```
+
+
+### Set Configuration
+
+```
+import strategicc.config as cfg
+from pathlib import Path
+
+cfg.LULC_PATH          = Path("2022.tif")
+cfg.STATE_CLASSES_CSV  = Path("25062026 State Class.csv")
+cfg.TRANSITIONS_CSV    = Path("23062026_stsm_transition_probabilities.csv")
+cfg.SPATIAL_MULT_CSV   = Path("27062026 Transition Spatial Multipliers.csv")
+cfg.TRANSITION_MULT_CSV= Path("27062026 Transition Multipliers.csv")
+cfg.MULT_DIR           = Path("mult_spat/")   #folder for transition spatial multiplier
+cfg.OUT_DIR            = Path("strategicc_test") #output folder
+
+
+cfg.ADJACENCY_STRENGTH   = 2
+cfg.START_YEAR           = 2022
+cfg.N_TIMESTEPS          = 30
+cfg.N_ITERATIONS         = 100    
+cfg.RNG_SEED             = 42
+
+cfg.USE_ADJACENCY        = True
+cfg.USE_SPATIAL_MULT     = True
+cfg.USE_TRANS_MULTIPLIER = True
+```
+
+### Diagnose Configuration
+
+```
+from strategicc import STSMEngine
+
+engine = STSMEngine.from_config()
+engine.load()
+engine.diagnostic()
+```
+
+### Run Engine
+
+```
+engine.run()
+```
+
+### Show Summary Plot
+
+```
+from strategicc import outputs
+
+summary_dir = engine.out_dir / "summary"
+
+print("Building summary tables...")
+area_df, trans_df = outputs.build_summary_tables(engine.iter_dirs, summary_dir)
+
+print("Plotting area envelope...")
+outputs.plot_area_envelope(area_df, engine.classes, summary_dir)
+
+print("Plotting transition envelope...")
+outputs.plot_transition_envelope(trans_df, summary_dir)
+
+Show plots inline
+from IPython.display import Image, display
+display(Image(str(summary_dir / "area_envelope.png")))
+display(Image(str(summary_dir / "transition_envelope.png")))
+```

strategicc-2.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "strategicc"
+version = "2.2.0"
+description = "State and Transition Integrated Economic-Environmental Accounting"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Shlhnj" }]
+keywords = [
+    "STSM", "land cover", "ecosystem accounting",
+    "SEEA-EA", "landscape ecology", "Monte Carlo",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Intended Audience :: Science/Research",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "Pillow>=10.0",
+    "matplotlib>=3.7",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-cov"]
+
+[project.urls]
+Homepage   = "https://github.com/Shlhnj/strategicc"
+Repository = "https://github.com/Shlhnj/strategicc"
+Issues     = "https://github.com/Shlhnj/strategicc/issues"
+
+[project.scripts]
+strategicc = "strategicc.run:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["strategicc*"]

strategicc-2.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

strategicc-2.2.0/strategicc/__init__.py

@@ -0,0 +1,9 @@
+"""
+strategicc — State and Transition Integrated Economic-Environmental Accounting
+v2.0
+"""
+
+from .engine import StrategiccEngine
+
+__version__ = "2.2.0"
+__all__ = ["StrategiccEngine"]

strategicc-2.2.0/strategicc/accounting/__init__.py

@@ -0,0 +1,12 @@
+"""
+strategicc/accounting  —  SEEA-EA accounting module  v2.0
+----------------------------------------------------------
+Produces ecosystem extent, physical flow, monetary flow,
+transition matrix, and change-in-value accounts from
+simulation outputs.
+"""
+
+from .seea import SEEAAccount
+from .csv_loader import load_ecosystem_services, EcosystemService
+
+__all__ = ["SEEAAccount", "load_ecosystem_services", "EcosystemService"]

strategicc-2.2.0/strategicc/accounting/csv_loader.py

@@ -0,0 +1,113 @@
+"""
+strategicc/accounting/csv_loader.py
+-------------------------------------
+Parse EcosystemServices.csv into EcosystemService dataclasses.
+
+CSV format (two modes supported):
+
+Mode A — monetary value per ha only (no physical unit):
+    StateClassId, ServiceName, ServiceType, ValuePerHa, Currency
+    Mangrove, Ecotourism, Cultural, 12500000, IDR
+
+Mode B — physical unit + monetary value per ha:
+    StateClassId, ServiceName, ServiceType, ValuePerHa, Currency, PhysicalUnit, PhysicalValuePerHa
+    Mangrove, Carbon Sequestration, Regulating, 97500000, IDR, MgC/ha, 1300
+
+ServiceType must be one of: Provisioning, Regulating, Cultural
+"""
+
+from __future__ import annotations
+import csv
+from dataclasses import dataclass
+from pathlib import Path
+
+
+VALID_SERVICE_TYPES = {"Provisioning", "Regulating", "Cultural"}
+
+
+@dataclass
+class EcosystemService:
+    """One ecosystem service entry from EcosystemServices.csv."""
+    state_class:        str           # matches StateClass name e.g. "Mangrove"
+    service_name:       str           # e.g. "Carbon Sequestration"
+    service_type:       str           # "Provisioning" | "Regulating" | "Cultural"
+    value_per_ha:       float         # monetary value per hectare per year
+    currency:           str           # e.g. "IDR"
+    physical_unit:      str | None    # e.g. "MgC/ha" — None if Mode A
+    physical_per_ha:    float | None  # physical quantity per ha — None if Mode A
+
+    @property
+    def has_physical(self) -> bool:
+        return self.physical_unit is not None and self.physical_per_ha is not None
+
+
+def load_ecosystem_services(path: str | Path) -> list[EcosystemService]:
+    """
+    Parse EcosystemServices.csv.
+
+    Required columns:
+        StateClassId, ServiceName, ServiceType, ValuePerHa, Currency
+
+    Optional columns (Mode B):
+        PhysicalUnit, PhysicalValuePerHa
+
+    Returns
+    -------
+    list of EcosystemService
+    """
+    path = Path(path)
+    services: list[EcosystemService] = []
+
+    with path.open(newline="", encoding="utf-8-sig") as fh:
+        reader = csv.DictReader(fh)
+        for i, row in enumerate(reader, start=2):
+            state_class  = row.get("StateClassId", "").strip()
+            service_name = row.get("ServiceName", "").strip()
+            service_type = row.get("ServiceType", "").strip()
+            currency     = row.get("Currency", "").strip()
+
+            # Parse monetary value
+            try:
+                value_per_ha = float(row.get("ValuePerHa", "").strip())
+            except (ValueError, AttributeError):
+                print(f"  [Warning] Row {i}: invalid ValuePerHa — skipped")
+                continue
+
+            # Validate service type
+            if service_type not in VALID_SERVICE_TYPES:
+                print(f"  [Warning] Row {i}: unknown ServiceType '{service_type}' "
+                      f"— must be one of {VALID_SERVICE_TYPES}")
+                continue
+
+            if not state_class or not service_name:
+                print(f"  [Warning] Row {i}: missing StateClassId or ServiceName — skipped")
+                continue
+
+            # Optional physical columns (Mode B)
+            phys_unit = row.get("PhysicalUnit", "").strip() or None
+            phys_raw  = row.get("PhysicalValuePerHa", "").strip()
+            try:
+                phys_per_ha = float(phys_raw) if phys_raw else None
+            except ValueError:
+                phys_per_ha = None
+
+            # Both must be present for Mode B, or both absent for Mode A
+            if (phys_unit is None) != (phys_per_ha is None):
+                print(f"  [Warning] Row {i} ({state_class} / {service_name}): "
+                      "PhysicalUnit and PhysicalValuePerHa must both be present "
+                      "or both absent — treating as Mode A")
+                phys_unit = phys_per_ha = None
+
+            services.append(EcosystemService(
+                state_class     = state_class,
+                service_name    = service_name,
+                service_type    = service_type,
+                value_per_ha    = value_per_ha,
+                currency        = currency,
+                physical_unit   = phys_unit,
+                physical_per_ha = phys_per_ha,
+            ))
+
+    print(f"  {len(services)} ecosystem service entries loaded "
+          f"({sum(s.has_physical for s in services)} with physical units)")
+    return services

strategicc-2.2.0/strategicc/accounting/outputs.py

@@ -0,0 +1,260 @@
+"""
+strategicc/accounting/outputs.py  —  SEEA-EA output functions  v2.0
+--------------------------------------------------------------------
+Saves all ecosystem accounts as CSVs and generates plots.
+
+Functions
+---------
+save_all_accounts   — save all account tables to CSV
+plot_monetary_flows — stacked area chart of total ecosystem value over time
+plot_value_by_service — line chart per service type over time
+plot_transition_heatmap — heatmap of transition matrix (area and value)
+"""
+
+from __future__ import annotations
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import matplotlib.ticker as mticker
+
+from strategicc.io.csv_loader import StateClass
+from strategicc.accounting.seea import SEEAAccount
+
+
+# ── Color helpers ─────────────────────────────────────────────────────────────
+
+def _class_colors(classes: dict[int, StateClass]) -> dict[str, tuple]:
+    return {
+        sc.name: (sc.color[1]/255, sc.color[2]/255, sc.color[3]/255)
+        for sc in classes.values()
+    }
+
+
+# ── Save all account tables ───────────────────────────────────────────────────
+
+def save_all_accounts(
+    acct:    SEEAAccount,
+    out_dir: Path,
+) -> None:
+    """Save all SEEA-EA account tables as CSVs."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    acct.extent_account().to_csv(out_dir / "seea_extent_account.csv")
+    print(f"  Saved: seea_extent_account.csv")
+
+    acct.transition_matrix().to_csv(out_dir / "seea_transition_matrix_area.csv")
+    print(f"  Saved: seea_transition_matrix_area.csv")
+
+    acct.value_change_matrix().to_csv(out_dir / "seea_transition_matrix_value.csv")
+    print(f"  Saved: seea_transition_matrix_value.csv")
+
+    acct.monetary_flow_account().to_csv(out_dir / "seea_monetary_flow_account.csv")
+    print(f"  Saved: seea_monetary_flow_account.csv")
+
+    phys = acct.physical_flow_account()
+    if phys is not None:
+        phys.to_csv(out_dir / "seea_physical_flow_account.csv")
+        print(f"  Saved: seea_physical_flow_account.csv")
+
+    acct.total_value_by_class().to_csv(out_dir / "seea_total_value_by_class.csv")
+    print(f"  Saved: seea_total_value_by_class.csv")
+
+    acct.change_in_value().to_csv(out_dir / "seea_change_in_value.csv")
+    print(f"  Saved: seea_change_in_value.csv")
+
+    acct.uncertainty_summary().to_csv(out_dir / "seea_uncertainty_summary.csv", index=False)
+    print(f"  Saved: seea_uncertainty_summary.csv")
+
+
+# ── Plot: stacked area — total ecosystem value over time ──────────────────────
+
+def plot_monetary_flows(
+    acct:    SEEAAccount,
+    classes: dict[int, StateClass],
+    out_dir: Path,
+    filename: str = "seea_monetary_flows.png",
+) -> None:
+    """
+    Stacked area chart: total ecosystem service value per class over time.
+    Shows which classes contribute most to total landscape value.
+    """
+    out_dir.mkdir(parents=True, exist_ok=True)
+    tv      = acct.total_value_by_class()
+    colors  = _class_colors(classes)
+    years   = tv.index.tolist()
+
+    fig, axes = plt.subplots(2, 1, figsize=(12, 10))
+
+    # ── Panel 1: stacked area by class ────────────────────────────────────────
+    ax1    = axes[0]
+    bottom = np.zeros(len(years))
+    for col in tv.columns:
+        vals  = tv[col].values
+        color = colors.get(col, (0.5, 0.5, 0.5))
+        ax1.fill_between(years, bottom, bottom + vals,
+                         alpha=0.85, color=color, label=col)
+        bottom += vals
+
+    ax1.set_ylabel("Total ecosystem value (currency/yr)", fontsize=10)
+    ax1.set_title("Total Ecosystem Service Value by Class", fontsize=11)
+    ax1.legend(loc="upper right", fontsize=8, framealpha=0.8)
+    ax1.yaxis.set_major_formatter(mticker.FuncFormatter(
+        lambda x, _: f"{x/1e6:.1f}M" if x >= 1e6 else f"{x:,.0f}"
+    ))
+    ax1.grid(True, alpha=0.2)
+
+    # ── Panel 2: year-on-year change in total value ───────────────────────────
+    ax2   = axes[1]
+    delta = acct.change_in_value()["Total"].dropna()
+    colors_bar = ["#2ecc71" if v >= 0 else "#e74c3c" for v in delta.values]
+    ax2.bar(delta.index, delta.values, color=colors_bar, alpha=0.85, width=0.7)
+    ax2.axhline(0, color="black", linewidth=0.8)
+    ax2.set_xlabel("Year", fontsize=10)
+    ax2.set_ylabel("Change in value (currency/yr)", fontsize=10)
+    ax2.set_title("Year-on-Year Change in Total Ecosystem Value", fontsize=11)
+    ax2.yaxis.set_major_formatter(mticker.FuncFormatter(
+        lambda x, _: f"{x/1e6:.1f}M" if abs(x) >= 1e6 else f"{x:,.0f}"
+    ))
+    ax2.grid(True, alpha=0.2, axis="y")
+
+    # ── Uncertainty band on panel 1 ───────────────────────────────────────────
+    unc    = acct.uncertainty_summary().set_index("Year")
+    total  = acct.total_value_by_class().sum(axis=1)
+    if not unc.empty:
+        ax1.fill_between(
+            unc.index, unc["Min value"], unc["Max value"],
+            alpha=0.12, color="grey", label="Min–Max range"
+        )
+        ax1.legend(loc="upper right", fontsize=8, framealpha=0.8)
+
+    plt.tight_layout()
+    out_path = out_dir / filename
+    fig.savefig(out_path, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+    print(f"  Saved: {out_path}")
+
+
+# ── Plot: line chart per service type ─────────────────────────────────────────
+
+def plot_value_by_service(
+    acct:    SEEAAccount,
+    out_dir: Path,
+    filename: str = "seea_value_by_service.png",
+) -> None:
+    """
+    Line chart: total monetary value per service type over time.
+    One line per service (Provisioning / Regulating / Cultural).
+    """
+    out_dir.mkdir(parents=True, exist_ok=True)
+    mf    = acct.monetary_flow_account()
+    years = mf.index.tolist()
+
+    # Aggregate by service type (top level of MultiIndex columns)
+    type_totals: dict[str, list[float]] = {}
+    for col in mf.columns:
+        stype = col[0]
+        type_totals.setdefault(stype, np.zeros(len(years)))
+        type_totals[stype] += mf[col].values
+
+    type_colors = {
+        "Provisioning": "#e67e22",
+        "Regulating":   "#27ae60",
+        "Cultural":     "#8e44ad",
+    }
+
+    fig, ax = plt.subplots(figsize=(12, 5))
+    for stype, vals in type_totals.items():
+        color = type_colors.get(stype, "#2c3e50")
+        ax.plot(years, vals, color=color, linewidth=2.5, label=stype, zorder=3)
+        ax.fill_between(years, 0, vals, color=color, alpha=0.08, zorder=2)
+
+    # Also plot individual services as thin dashed lines
+    for col in mf.columns:
+        stype = col[0]
+        sname = col[1]
+        color = type_colors.get(stype, "#2c3e50")
+        ax.plot(years, mf[col].values, color=color,
+                linewidth=0.8, linestyle="--", alpha=0.5,
+                label=f"  {sname}")
+
+    ax.set_xlabel("Year", fontsize=10)
+    ax.set_ylabel("Value (currency/yr)", fontsize=10)
+    ax.set_title("Ecosystem Service Value by Service Type", fontsize=11)
+    ax.yaxis.set_major_formatter(mticker.FuncFormatter(
+        lambda x, _: f"{x/1e6:.1f}M" if x >= 1e6 else f"{x:,.0f}"
+    ))
+    ax.legend(loc="upper right", fontsize=8, framealpha=0.8, ncol=2)
+    ax.grid(True, alpha=0.2)
+
+    plt.tight_layout()
+    out_path = out_dir / filename
+    fig.savefig(out_path, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+    print(f"  Saved: {out_path}")
+
+
+# ── Plot: transition heatmap ──────────────────────────────────────────────────
+
+def plot_transition_heatmap(
+    acct:    SEEAAccount,
+    out_dir: Path,
+    filename: str = "seea_transition_heatmap.png",
+) -> None:
+    """
+    Two-panel heatmap:
+    Left  — area (ha) converted between classes (transition matrix)
+    Right — monetary value change from those conversions
+    """
+    out_dir.mkdir(parents=True, exist_ok=True)
+    tm = acct.transition_matrix()
+    vm = acct.value_change_matrix()
+
+    if tm.empty:
+        print("  [Skip] transition matrix empty — no heatmap generated")
+        return
+
+    fig, axes = plt.subplots(1, 2, figsize=(16, 6))
+
+    for ax, data, title, cmap, fmt in [
+        (axes[0], tm, "Area converted (ha)",    "YlOrBr", ".1f"),
+        (axes[1], vm, "Value change (currency)", "RdYlGn", ".0f"),
+    ]:
+        arr = data.values.astype(float)
+
+        # Mask diagonal (no-change cells)
+        mask_diag = np.eye(arr.shape[0], dtype=bool)
+        arr_plot  = np.where(mask_diag, np.nan, arr)
+
+        vmax = np.nanmax(np.abs(arr_plot)) if not np.all(np.isnan(arr_plot)) else 1
+        vmin = -vmax if cmap == "RdYlGn" else 0
+
+        im = ax.imshow(arr_plot, cmap=cmap, vmin=vmin, vmax=vmax, aspect="auto")
+        plt.colorbar(im, ax=ax, shrink=0.8)
+
+        labels = list(data.index)
+        ax.set_xticks(range(len(labels)))
+        ax.set_yticks(range(len(labels)))
+        ax.set_xticklabels(labels, rotation=45, ha="right", fontsize=8)
+        ax.set_yticklabels(labels, fontsize=8)
+        ax.set_xlabel("To class", fontsize=9)
+        ax.set_ylabel("From class", fontsize=9)
+        ax.set_title(title, fontsize=10)
+
+        # Annotate non-zero, non-diagonal cells
+        for i in range(arr.shape[0]):
+            for j in range(arr.shape[1]):
+                if not mask_diag[i, j] and arr[i, j] != 0:
+                    ax.text(j, i, f"{arr[i,j]:{fmt}}",
+                            ha="center", va="center", fontsize=7,
+                            color="black")
+
+    plt.suptitle("Ecosystem Transition Matrix", fontsize=12, y=1.01)
+    plt.tight_layout()
+    out_path = out_dir / filename
+    fig.savefig(out_path, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+    print(f"  Saved: {out_path}")