Source code for deeprootgen.calibration.summary_statistics

"""Contains utilities for calibrating models from summary statistics.

This module defines utility functions for calibrating simulation models from summary statistics.
"""

from deeprootgen.statistics.summary_statistics import RootLengthDensity
import numpy as np
import pandas as pd

from ..data_model import (
    RootCalibrationModel,
    RootSimulationModel,
    SummaryStatisticsModel,
)
from ..model import RootSystemSimulation
from ..statistics import (
    DistanceMetricBase,
    get_distance_metric_func,
    get_summary_statistic_func,
)
from ..statistics.spatial_rld import calculate_core_rld


[docs] def get_calibration_summary_stats(input_parameters: RootCalibrationModel) -> tuple: """Extract summary statistics needed for model calibration. Args: input_parameters (RootCalibrationModel): The root calibration data model. Raises: ValueError: Error thrown when the summary statistic list is empty. Returns: tuple: The calibration distance metric and summary statistics. """ statistics_comparison = input_parameters.statistics_comparison distance_metrics = [] if isinstance(statistics_comparison.distance_metrics, list): # type: ignore[union-attr] for distance_metric in statistics_comparison.distance_metrics: # type: ignore[union-attr] distance_func = get_distance_metric_func(distance_metric) distance = distance_func() distance_metrics.append(distance) statistics_list: list[SummaryStatisticsModel] = [] if input_parameters.summary_statistics is None: return distance_metrics, statistics_list input_statistics = [] for summary_statistic in input_parameters.summary_statistics: statistics_list.append(summary_statistic.dict()) input_statistics.append(summary_statistic.statistic_name) summary_statistics = set( # noqa: F841 statistics_comparison.summary_statistics # type: ignore ).intersection(input_statistics) statistics_records = ( pd.DataFrame(statistics_list) .query("statistic_name in @summary_statistics") .to_dict("records") ) if len(statistics_records) == 0: raise ValueError("Summary statistics list cannot be empty.") statistics_list = [ SummaryStatisticsModel.parse_obj(statistic) for statistic in statistics_records ] return distance_metrics, statistics_list
[docs] def run_calibration_simulation( parameter_specs: dict, input_parameters: RootCalibrationModel, ) -> tuple: """Run a simulation for model calibration purposes. Args: parameter_specs (dict): The simulation parameter specification. input_parameters (RootCalibrationModel): The root calibration data model. Returns: tuple: The simulation and its parameters. """ parameter_specs["random_seed"] = input_parameters.random_seed simulation_parameters = RootSimulationModel.parse_obj(parameter_specs) simulation = RootSystemSimulation( simulation_tag=input_parameters.simulation_tag, # type: ignore random_seed=input_parameters.random_seed, # type: ignore ) simulation.run(simulation_parameters) return simulation, simulation_parameters
[docs] def calculate_summary_statistics( parameter_specs: dict, input_parameters: RootCalibrationModel, statistics_list: list[SummaryStatisticsModel], ) -> tuple: """Calculate summary statistics for observed and simulated data. Args: parameter_specs (dict): The simulation parameter specification. input_parameters (RootCalibrationModel): The root calibration data model. statistics_list (list[SummaryStatisticsModel]): The list of summary statistics. Returns: tuple: The simulated and observed data. """ simulation, simulation_parameters = run_calibration_simulation( parameter_specs, input_parameters ) node_df, _ = simulation.G.as_df() # Build a soil grid if RLD is being calibrated. rld_requested = any( s.statistic_name == "root_length_density" for s in statistics_list ) soil_df = None if rld_requested: dimensions = [ input_parameters.soil_layer_height, input_parameters.soil_layer_width, input_parameters.soil_n_layers, input_parameters.soil_n_cols, ] if any(v is None or v <= 0 for v in dimensions): raise ValueError("RLD calibration requires valid soil dimensions.") soil_df = simulation.soil.create_soil_grid( input_parameters.soil_layer_height, input_parameters.soil_n_layers, input_parameters.soil_layer_width, input_parameters.soil_n_cols, ) # Only for the original Soil implementation. soil_df = soil_df.rename(columns={"y": "z", "z": "y"}) observed_values = [] simulated_values = [] for statistic in statistics_list: statistic_name = statistic.statistic_name if statistic_name == "root_length_density": is_spatial = any( value is not None for value in ( statistic.x, statistic.y, statistic.core_radius, ) ) if is_spatial: if any( value is None for value in ( statistic.x, statistic.y, statistic.core_radius, ) ): raise ValueError("Spatial RLD requires x, y and core_radius.") statistic_value = calculate_core_rld( node_df, x=statistic.x, y=statistic.y, z_lower_bound=statistic.z_lower_bound, z_upper_bound=statistic.z_upper_bound, core_radius=statistic.core_radius, diameter_max_mm=statistic.diameter_max_mm, plant_id=statistic.plant_id, ) else: # Existing whole-grid RLD calculation. # soil_df must be generated beforehand. statistic_value = RootLengthDensity(soil_df=soil_df).calculate(node_df) else: statistic_func = get_summary_statistic_func(statistic_name) statistic_instance = statistic_func( root_tissue_density=(simulation_parameters.root_tissue_density) ) statistic_value = statistic_instance.calculate(node_df) if not np.isscalar(statistic_value): continue observed_values.append(statistic.statistic_value) simulated_values.append(float(statistic_value)) observed = np.array(observed_values).flatten() simulated = np.array(simulated_values).flatten() return simulated, observed
[docs] def calculate_summary_statistic_discrepancy( parameter_specs: dict, input_parameters: RootCalibrationModel, statistics_list: list[SummaryStatisticsModel], distances: list[DistanceMetricBase], ) -> float: """Calculate the discrepancy between simulated and observed data. Args: parameter_specs (dict): The simulation parameter specification. input_parameters (RootCalibrationModel): The root calibration data model. statistics_list (list[SummaryStatisticsModel]): The list of summary statistics. distances (list[DistanceMetricBase]): The distance metric object. Returns: float: The discrepancy between simulated and observed data. """ simulated, observed = calculate_summary_statistics( parameter_specs, input_parameters, statistics_list ) discrepancy_list = [] for distance in distances: discrepancy = distance.calculate(observed, simulated) discrepancy_list.append(discrepancy) discrepancies: float = np.array(discrepancy_list).flatten().sum() return discrepancies