Update README and model docs: reflect modular structure, active/archived models, and model-driven dashboard

dashboard/app.py

@@ -21,9 +21,9 @@ from src.allometry import calculate_biomass
 import copy
 
 MODEL_CONFIGS = {
-    "Original Model": "configs/params.yaml",
-    "Simple Linear": "configs/linear.yaml",
-    "Linear Plateau": "configs/linear_plateau.yaml",
+    # "Original Model": "configs/params.yaml",  # ARCHIVED/NOT IN USE
+    # "Simple Linear": "configs/linear.yaml",   # ARCHIVED/NOT IN USE
+    # "Linear Plateau": "configs/linear_plateau.yaml",  # ARCHIVED/NOT IN USE
     "Declining Increment": "configs/declining_increment.yaml"
 }
 
@@ -44,29 +44,20 @@ def update_planting_schedule(config_path, year_areas):
 def create_survival_table(model):
     """
     Returns a DataFrame with years as rows and columns for each species and total surviving trees.
+    Uses model.species_metrics for all values.
     """
-    years = range(1, model.project.duration_years + 1)
-    data = {"Year": []}
-    # Use internal names for lookup, but display friendly names
-    internal_names = [s.name for s in model.species]
-    display_names = [SPECIES_DISPLAY_NAMES.get(s.name, s.name) for s in model.species]
-    for name in display_names:
-        data[name] = []
-    data["Total Surviving Trees"] = []
-    for year in years:
-        data["Year"].append(year)
-        totals = model.calculate_total_surviving_trees(year)
-        total = 0
-        for internal, display in zip(internal_names, display_names):
-            val = totals.get(internal, 0)
-            data[display].append(val)
-            total += val
-        data["Total Surviving Trees"].append(total)
-    df = pd.DataFrame(data)
-    # Format numbers: no decimals, thousands separator
-    for name in display_names + ["Total Surviving Trees"]:
-        df[name] = df[name].apply(lambda x: f"{x:,.0f}")
-    return df
+    df = model.species_metrics.copy()
+    # Pivot to wide format: years as rows, species as columns
+    surv = df.pivot(index="Year", columns="Species", values="Surviving Trees")
+    # Rename columns to display names
+    surv.columns = [SPECIES_DISPLAY_NAMES.get(sp, sp) for sp in surv.columns]
+    # Add total surviving trees column
+    surv["Total Surviving Trees"] = surv.sum(axis=1)
+    # Format numbers
+    for col in surv.columns:
+        surv[col] = surv[col].apply(lambda x: f"{x:,.0f}")
+    surv = surv.reset_index()
+    return surv
 
 def run_model_from_config(config):
     with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as tmp:
@@ -195,53 +186,25 @@ def create_all_plots(results, species_results, config):
     fig2.add_trace(go.Bar(x=results["year"], y=annual_ers, name="Annual ERs", marker_color="#2ecc71", opacity=0.7))
     fig2.update_layout(title="Annual Emission Reductions", xaxis_title="Year", yaxis_title="Annual ERs (tCO2)", hovermode="x unified", template="plotly_white")
 
-    # 3. Biomass per tree for all species
+    # 3. Biomass per tree for all species (refactored to use model.species_metrics)
     years = results["year"]
     fig3 = go.Figure()
+    import tempfile, yaml
     from src.er_model import ERModel
-    growth_model = config.get('growth_model', 'chapman_richards')
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as tmp:
+        yaml.dump(config, tmp)
+        tmp_path = tmp.name
+    model = ERModel(Path(tmp_path))
+    model.run()
+    df = model.species_metrics.copy()
     for sp in config["species"]:
         name = SPECIES_DISPLAY_NAMES.get(sp["name"], sp["name"])
-        initial_dbh = sp["initial_values"]["dbh"]
-        initial_height = sp["initial_values"]["height"]
-        use_continuous = config.get('continuous_growth', False)
-        if growth_model == "linear":
-            dbh_params = sp["linear"]["dbh"]
-            height_params = sp["linear"]["height"]
-            dbh = [ERModel.linear_growth(t, dbh_params, initial_dbh) for t in years]
-            height = [ERModel.linear_growth(t, height_params, initial_height) for t in years]
-        elif growth_model == "linear_plateau":
-            dbh_params = sp["linear_plateau"]["dbh"]
-            height_params = sp["linear_plateau"]["height"]
-            dbh = [ERModel.linear_plateau_growth(t, dbh_params, initial_dbh) for t in years]
-            height = [ERModel.linear_plateau_growth(t, height_params, initial_height) for t in years]
-        elif growth_model == "declining_increment":
-            dbh_params = sp["declining_increment"]["dbh"]
-            height_params = sp["declining_increment"]["height"]
-            if use_continuous:
-                dbh = [ERModel.continuous_declining_increment_growth(t, dbh_params, initial_dbh) for t in years]
-                height = [ERModel.continuous_declining_increment_growth(t, height_params, initial_height) for t in years]
-            else:
-                dbh = [ERModel.declining_increment_growth(t, dbh_params, initial_dbh) for t in years]
-                height = [ERModel.declining_increment_growth(t, height_params, initial_height) for t in years]
-        else:  # Default to Chapman-Richards
-            dbh_params = sp["chapman_richards"]["dbh"]
-            height_params = sp["chapman_richards"]["height"]
-            def chapman_richards(t, params, initial):
-                a, b, c = params["a"], params["b"], params["c"]
-                return initial + (a - initial) * (1 - np.exp(-b * t)) ** c
-            dbh = [chapman_richards(t, dbh_params, initial_dbh) for t in years]
-            height = [chapman_richards(t, height_params, initial_height) for t in years]
-        if "Zanvo" in sp["allometry"]["equation"]:
-            if "1.938" in sp["allometry"]["equation"]:
-                biomass = 1.938 * (np.array(dbh) ** 2 * np.array(height)) ** 0.67628 / 1000
-            else:
-                biomass = 1.486 * (np.array(dbh) ** 2 * np.array(height)) ** 0.55864 / 1000
-        else:
-            biomass = dbh
-        check_complex(biomass, f"{name} biomass (allometry)")
-        fig3.add_trace(go.Scatter(x=years, y=biomass, mode="lines+markers", name=name, line=dict(width=2)))
-    fig3.update_layout(title="Total Biomass per Tree", xaxis_title="Year since planting", yaxis_title="Biomass (tonnes per tree)", hovermode="x unified", template="plotly_white")
+        # Get per-tree biomass for this species
+        sp_biomass = df[df["Species"] == sp["name"]].set_index("Year")["Biomass per Tree (kg)"]
+        # Ensure correct order and fill missing years with NaN
+        sp_biomass = sp_biomass.reindex(years)
+        fig3.add_trace(go.Scatter(x=years, y=sp_biomass, mode="lines+markers", name=name, line=dict(width=2)))
+    fig3.update_layout(title="Total Biomass per Tree", xaxis_title="Year since planting", yaxis_title="Biomass (kg per tree)", hovermode="x unified", template="plotly_white")
     return (fig1, fig2, fig3)
 
 def create_summary(results, species_results, config, model):
@@ -356,66 +319,22 @@ def create_biomass_debug_table(config):
     - Surviving Trees
     - DBH (cm)
     - Height (m)
-    - Biomass per tree (kg)
+    - Biomass per Tree (kg)
     - Total Biomass (kg)
-    Uses cohort-level growth (age = year - planting_year + 1).
+    Uses model.species_metrics for all values.
     """
     from src.er_model import ERModel
-    from src.allometry import calculate_biomass
-    years = range(1, config["project"]["duration_years"] + 1)
-    data = {}
-    for sp in config["species"]:
-        sp_disp = SPECIES_DISPLAY_NAMES.get(sp["name"], sp["name"])
-        data[(sp_disp, "Surviving Trees")] = []
-        data[(sp_disp, "DBH (cm)")] = []
-        data[(sp_disp, "Height (m)")] = []
-        data[(sp_disp, "Biomass per Tree (kg)")] = []
-        data[(sp_disp, "Total Biomass (kg)")] = []
-    model = ERModel(config=config)
-    for year in years:
-        for sp in config["species"]:
-            sp_disp = SPECIES_DISPLAY_NAMES.get(sp["name"], sp["name"])
-            total_surviving = 0
-            total_biomass = 0
-            total_dbh = 0
-            total_height = 0
-            total_biomass_per_tree = 0
-            n_cohorts = 0
-            for planting_year, area in config["project"]["planting_schedule"].items():
-                py = int(planting_year.split("_")[1])
-                cohort_age = year - py + 1
-                if cohort_age < 1:
-                    continue
-                initial_trees = sp["planting_density"] * area
-                plateau_density = sp["planting_density"] * area if cohort_age >= 5 else None
-                surviving = model.calculate_cohort_surviving_trees(1, cohort_age, initial_trees, model.species[0], plateau_density, model.growth_model)
-                dbh_func, dbh_params = model.get_growth_function_and_params(model.species[0], model.growth_model, 'dbh')
-                height_func, height_params = model.get_growth_function_and_params(model.species[0], model.growth_model, 'height')
-                dbh = dbh_func(cohort_age, dbh_params, sp["initial_values"]["dbh"])
-                height = height_func(cohort_age, height_params, sp["initial_values"]["height"])
-                biomass_per_tree = calculate_biomass(dbh, height, sp["name"], sp["allometry"])
-                total_surviving += surviving
-                total_dbh += dbh * surviving
-                total_height += height * surviving
-                total_biomass_per_tree += biomass_per_tree * surviving
-                total_biomass += biomass_per_tree * surviving
-                n_cohorts += surviving
-            if total_surviving > 0:
-                avg_dbh = total_dbh / total_surviving
-                avg_height = total_height / total_surviving
-                avg_biomass_per_tree = total_biomass_per_tree / total_surviving
-            else:
-                avg_dbh = 0
-                avg_height = 0
-                avg_biomass_per_tree = 0
-            data[(sp_disp, "Surviving Trees")].append(total_surviving)
-            data[(sp_disp, "DBH (cm)")].append(avg_dbh)
-            data[(sp_disp, "Height (m)")].append(avg_height)
-            data[(sp_disp, "Biomass per Tree (kg)")].append(avg_biomass_per_tree)
-            data[(sp_disp, "Total Biomass (kg)")].append(total_biomass)
-    columns = pd.MultiIndex.from_tuples(list(data.keys()))
-    df = pd.DataFrame({col: data[col] for col in columns}, index=range(1, config["project"]["duration_years"] + 1))
-    df.index.name = "Year"
+    import tempfile, yaml
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as tmp:
+        yaml.dump(config, tmp)
+        tmp_path = tmp.name
+    model = ERModel(Path(tmp_path))
+    model.run()
+    df = model.species_metrics.copy()
+    # Pivot to multi-index columns: (Species, Metric)
+    df = df.pivot(index="Year", columns="Species")
+    # Flatten columns
+    df.columns = [f"{SPECIES_DISPLAY_NAMES.get(sp, sp)}, {metric}" for metric, sp in df.columns]
     # Format numbers
     for col in df.columns:
         if "Surviving Trees" in col:
@@ -481,7 +400,7 @@ with gr.Blocks() as demo:
                 for col in species_results_fmt.columns:
                     if species_results_fmt[col].dtype in [float, int]:
                         species_results_fmt[col] = species_results_fmt[col].apply(lambda x: f"{x:,.2f}" if isinstance(x, float) else f"{x:,}")
-                return plots[0], plots[2], plots[1], growth_fig, summary, results_fmt, species_results_fmt, survival_table, biomass_debug_df
+                return plots[0], plots[1], plots[2], growth_fig, summary, results_fmt, species_results_fmt, survival_table, biomass_debug_df
 
             update_btn.click(
                 update_declining_increment,

src/er_model.py

@@ -13,6 +13,11 @@ import warnings
 from .allometry import calculate_biomass
 from .metrics import calculate_carbon
 
+# Growth model imports
+from .growth_models.declining_increment import declining_increment_growth, continuous_declining_increment_growth
+# from growth_models.chapman_richards import chapman_richards_growth  # ARCHIVED/NOT IN USE
+# from growth_models.linear import linear_growth, linear_plateau_growth  # ARCHIVED/NOT IN USE
+
 
 @dataclass
 class Species:
@@ -246,6 +251,7 @@ class ERModel:
         years = range(1, self.project.duration_years + 1)
         results = []
         species_results = []
+        species_metrics_rows = []  # For new per-year, per-species metrics
         for year in years:
             year_results = {"year": year}
             species_year_results = {"Year": year}
@@ -253,17 +259,57 @@ class ERModel:
             cumulative_area = self.calculate_cumulative_area(year)
             for species in self.species:
                 species_carbon = 0
+                # --- New metrics ---
+                total_surviving = 0
+                total_dbh = 0
+                total_height = 0
+                total_biomass_per_tree = 0
+                total_biomass = 0
+                n_cohorts = 0
                 for planting_year, area in self.project.planting_schedule.items():
                     py = int(planting_year.split("_")[1])
                     cohort_age = year - py + 1
                     if cohort_age < 1:
                         continue
-                    # Use correct cohort age for all calculations
+                    initial_trees = species.planting_density * area
+                    plateau_density = species.planting_density * area if cohort_age >= 5 else None
+                    surviving = self.calculate_cohort_surviving_trees(1, cohort_age, initial_trees, species, plateau_density, self.growth_model)
+                    dbh_func, dbh_params = self.get_growth_function_and_params(species, self.growth_model, 'dbh')
+                    height_func, height_params = self.get_growth_function_and_params(species, self.growth_model, 'height')
+                    dbh = dbh_func(cohort_age, dbh_params, species.initial_values["dbh"])
+                    height = height_func(cohort_age, height_params, species.initial_values["height"])
+                    biomass_per_tree = calculate_biomass(dbh, height, species.name, species.allometry)
+                    total_surviving += surviving
+                    total_dbh += dbh * surviving
+                    total_height += height * surviving
+                    total_biomass_per_tree += biomass_per_tree * surviving
+                    total_biomass += biomass_per_tree * surviving
+                    n_cohorts += surviving
+                    # --- End new metrics ---
+                    # Existing carbon calculation
                     carbon = self.calculate_carbon_for_species(species, year, area, cohort_age)
                     species_carbon += carbon
                 total_carbon += species_carbon
                 species_key = f"{species.name} tCO2"
                 species_year_results[species_key] = species_carbon
+                # Store per-year, per-species metrics
+                if total_surviving > 0:
+                    avg_dbh = total_dbh / total_surviving
+                    avg_height = total_height / total_surviving
+                    avg_biomass_per_tree = total_biomass_per_tree / total_surviving
+                else:
+                    avg_dbh = 0
+                    avg_height = 0
+                    avg_biomass_per_tree = 0
+                species_metrics_rows.append({
+                    "Year": year,
+                    "Species": species.name,
+                    "Surviving Trees": total_surviving,
+                    "DBH (cm)": avg_dbh,
+                    "Height (m)": avg_height,
+                    "Biomass per Tree (kg)": avg_biomass_per_tree,
+                    "Total Biomass (kg)": total_biomass
+                })
             species_year_results["Total tCO2"] = total_carbon
             species_year_results["Cumulative ha"] = cumulative_area
             species_year_results["tCO2/ha"] = total_carbon / cumulative_area if cumulative_area > 0 else 0
@@ -289,6 +335,7 @@ class ERModel:
             species_results.append(species_year_results)
         self.results = pd.DataFrame(results)
         self.species_results = pd.DataFrame(species_results)
+        self.species_metrics = pd.DataFrame(species_metrics_rows)
         return self.results, self.species_results
 
     def save_results(self, output_path: Path) -> None:
@@ -307,19 +354,22 @@ class ERModel:
         Returns the correct growth function and parameter dict for the given species and dimension (dbh or height).
         """
         if growth_model == "linear":
-            func = ERModel.linear_growth
+            # from growth_models.linear import linear_growth
+            func = None  # ARCHIVED/NOT IN USE
             params = species.linear[dim]
         elif growth_model == "linear_plateau":
-            func = ERModel.linear_plateau_growth
+            # from growth_models.linear import linear_plateau_growth
+            func = None  # ARCHIVED/NOT IN USE
             params = species.linear_plateau[dim]
         elif growth_model == "declining_increment":
             if getattr(self, 'continuous_growth', False):
-                func = ERModel.continuous_declining_increment_growth
+                func = continuous_declining_increment_growth
             else:
-                func = ERModel.declining_increment_growth
+                func = declining_increment_growth
             params = species.declining_increment[dim]
         else:
-            func = ERModel.chapman_richards_growth
+            # from growth_models.chapman_richards import chapman_richards_growth
+            func = None  # ARCHIVED/NOT IN USE
             params = species.chapman_richards[dim]
         return func, params
 

src/growth_models/chapman_richards.py

@@ -0,0 +1,11 @@
+"""
+Chapman-Richards Growth Model (ARCHIVED/NOT IN USE)
+"""
+import numpy as np
+
+def chapman_richards_growth(age: float, params: dict, initial_value: float) -> float:
+    """
+    Chapman-Richards growth function.
+    """
+    a, b, c = params["a"], params["b"], params["c"]
+    return initial_value + (a - initial_value) * (1 - np.exp(-b * age)) ** c 

src/growth_models/declining_increment.py

@@ -0,0 +1,31 @@
+"""
+Declining Increment Growth Model (ACTIVE)
+
+Contains both discrete and continuous forms.
+"""
+import numpy as np
+
+def declining_increment_growth(age: float, params: dict, initial_value: float) -> float:
+    """
+    Discrete declining increment growth: sum annual increments, never negative.
+    """
+    r0 = params["r0"]
+    T_m = params["T_m"]
+    total = initial_value
+    for i in range(1, int(np.floor(age)) + 1):
+        increment = r0 * max(0, 1 - (i - 1) / T_m)
+        total += increment
+    frac = age - int(np.floor(age))
+    if frac > 0:
+        i = int(np.floor(age)) + 1
+        increment = r0 * max(0, 1 - (i - 1) / T_m)
+        total += frac * increment
+    return total
+
+def continuous_declining_increment_growth(age: float, params: dict, initial_value: float) -> float:
+    """
+    Continuous declining increment growth: analytical formula.
+    """
+    r0 = params["r0"]
+    T_m = params["T_m"]
+    return initial_value + r0 * (age - age**2 / (2 * T_m)) 

src/growth_models/linear.py

@@ -0,0 +1,22 @@
+"""
+Linear and Linear Plateau Growth Models (ARCHIVED/NOT IN USE)
+"""
+
+def linear_growth(age: float, params: dict, initial_value: float) -> float:
+    """
+    Simple linear growth function.
+    """
+    r = params["r"]
+    return initial_value + r * age
+
+def linear_plateau_growth(age: float, params: dict, initial_value: float) -> float:
+    """
+    Linear growth with plateau.
+    """
+    r = params["r"]
+    T_p = params["T_p"]
+    a = params["a"]
+    if age <= T_p:
+        return initial_value + r * age
+    else:
+        return initial_value + a