cost_eco_model_linker.runner

Attributes

SEMVER_RE

Functions

evaluate(→ list[str])

Evaluate costs of intervention scenarios.

run_cost_exploration(→ dict)

Explore cost uncertainty across intervention scenarios.

summarise_mc_results(→ dict)

Summarise Monte Carlo cost exploration results produced by run_cost_exploration.

evaluate_production_cost(→ tuple[float, float])

Wrapper that converts factor kwargs into the format expected by

evaluate_deployment_cost(→ tuple[float, float])

Wrapper that converts factor kwargs into the format expected by

evaluate_lm_cost(→ pandas.DataFrame)

Evaluate the LM cost model over a year-by-year coral scenario and apply

run_cost_model(→ pandas.DataFrame)

Evaluate a cost model over a set of parameter combinations.

sample_joint_factors(→ tuple[pandas.DataFrame, ...)

Generate Sobol' samples over the combined factor space of all three models

run_joint_cost_models(→ tuple[pandas.DataFrame, ...)

Run production, deployment, and LM cost models against jointly-sampled parameters.

sweep_ca(→ pandas.DataFrame)

Sweep a single parameter across the CA production and deployment models.

sweep_lm(→ pandas.DataFrame)

Sweep a single parameter across the LM cost model.

Module Contents

cost_eco_model_linker.runner.SEMVER_RE
cost_eco_model_linker.runner.evaluate(rme_files_path: str, nsims: int, deploy_model_fn: str, prod_model_fn: str, lm_model_fn: str, results_dir: str, metrics: list = None, uncertainty_dict: dict = None, active_models: set = None, nprocs: int = 1, costs_only: bool = False, sample_scale: bool = False, distance_override_NM: float = None) → list[str]

Evaluate costs of intervention scenarios.

Parameters:

  • rme_files_path (str) – Path to ReefMod Engine results.

  • nsims (int) – Number of simulations to evaluate.

  • deploy_model_fn (str) – Path to deployment spreadsheet model, including filename but excluding file extension.

  • prod_model_fn (str) – Path to production spreadsheet model, including filename but excluding file extension.

  • results_dir (str) – Path to directory for storing results.

  • lm_model_fn (str) – Path to LM spreadsheet model, including filename but excluding file extension.

  • metrics (list, optional) – List of metrics to calculate. Default is None.

  • uncertainty_dict (dict, optional) – Dictionary specifying uncertainty parameters. Default is None.

  • active_models (set, optional) – Intervention types to include in cost calculations. Valid values are "outplant" and "lm". Defaults to both when None. Pass {"outplant"} for CA-only or {"lm"} for LM-only scenarios.

  • nprocs (int, optional) – Number of parallel worker processes for cost sampling. Each worker receives ceil(nsims / nprocs) draws. Defaults to 1 (serial).

  • costs_only (bool, optional) – When True, skips post-processing of ecological metric files. Use this when only cost outputs are needed (e.g. in run_cost_exploration). Defaults to False.

  • distance_override_NM (float, optional) – When set, replaces the geographic port-distance calculation with this fixed value (nautical miles) for all reefsets. Useful for best-guess explorer runs where the config best-point distance (e.g. 27 NM North, 54 NM Centre) should be used instead of the computed reef distance.

Returns:

Paths to result files.

Return type:

list[str]

cost_eco_model_linker.runner.run_cost_exploration(rme_template_path: str, nsims: int, deploy_model_fn: str, prod_model_fn: str, lm_model_fn: str, results_dir: str, assessment_year: int, reefset_CA: list = None, reefset_LM: list = None, metrics: list = None, uncertainty_dict: dict = None, nprocs=1) → dict

Explore cost uncertainty across intervention scenarios.

Prepares a scenario directory from the RME template (filtering to year 1 through assessment_year and optionally updating reef assignments), then calls evaluate() three times — combined (CA + LM), CA-only, and LM-only, writing each run’s cost outputs into a labelled subdirectory under results_dir. Ecological metric post-processing is skipped as only cost outputs are of interest here.

Parameters:

  • rme_template_path (str) – Path to the RME output directory to use as a template.

  • nsims (int) – Number of Monte Carlo draws for cost uncertainty sampling.

  • deploy_model_fn (str) – Path to deployment spreadsheet model (excluding extension).

  • prod_model_fn (str) – Path to production spreadsheet model (excluding extension).

  • lm_model_fn (str) – Path to LM spreadsheet model (excluding extension).

  • results_dir (str) – Root directory for outputs. Three subdirectories are created: combined/, ca_only/, and lm_only/.

  • assessment_year (int) – The second (target) deployment year. Year 1 (first deployment year) is always included; rows beyond assessment_year are dropped from the scenario before running.

  • reefset_CA (list, optional) – Reef IDs to assign to reefset_CA (e.g. ["18-096"]). If None, the template value from scenario_info.json is used.

  • reefset_LM (list, optional) – Reef IDs to assign to reefset_LM (e.g. ["16-071"]). If None, the template value from scenario_info.json is used.

  • metrics (list, optional) – Passed to evaluate() for ID key generation. Ecological metric files are not post-processed. Defaults to [rci, raw_rti, rfi].

  • uncertainty_dict (dict, optional) – Uncertainty parameters for ecological metrics. Defaults to default_uncertainty_dict().

  • nprocs (int, optional) – Number of cores to use.

Returns:

Mapping of scenario label to list of result file paths: {"combined": [...], "ca_only": [...], "lm_only": [...]}.

Return type:

dict

cost_eco_model_linker.runner.summarise_mc_results(results_dir: str, quantiles: list = None, scenario_id: int = 1) → dict

Summarise Monte Carlo cost exploration results produced by run_cost_exploration.

Reads the combined cost overview CSV from each scenario subdirectory (combined/, ca_only/, lm_only/), computes per-year quantiles across draws for each cost column, and returns a nested dict suitable for JSON serialisation and HTML visualisation.

Parameters:

  • results_dir (str) – Root directory passed to run_cost_exploration (parent of the combined/, ca_only/, and lm_only/ subdirectories).

  • quantiles (list, optional) – Quantile levels to compute, e.g. [0.05, 0.25, 0.5, 0.75, 0.95]. Defaults to [0.05, 0.25, 0.5, 0.75, 0.95].

  • scenario_id (int, optional) – Scenario ID used in the cost overview filename. Defaults to 1.

Returns:

Structure: {scenario: {cost_col: {year: {quantile_label: value}}}}. Also written to <results_dir>/mc_summary.json.

Return type:

dict

cost_eco_model_linker.runner.evaluate_production_cost(workbook_path: str, **factors) → tuple[float, float]

Wrapper that converts factor kwargs into the format expected by calculate_production_cost and returns operational and setup costs. Only the factors to be overridden need to be provided; all others default to their current values in the workbook.

Parameters:

  • workbook_path (str) – Absolute path to the Excel workbook including extension (.xlsx).

  • **factors – Factor name-value pairs keyed by factor_name from the config CSV. Only factors to be overridden need to be supplied.

Returns:

  • op_cost (float) – Operational cost.

  • setup_cost (float) – Setup cost.

cost_eco_model_linker.runner.evaluate_deployment_cost(workbook_path: str, **factors) → tuple[float, float]

Wrapper that converts factor kwargs into the format expected by calculate_deployment_cost and returns operational and setup costs. Only the factors to be overridden need to be provided; all others default to their current values in the workbook.

Parameters:

  • workbook_path (str) – Absolute path to the Excel workbook.

  • **factors – Factor name-value pairs keyed by factor_name from the config CSV. Only factors to be overridden need to be supplied. due to the leading digit making it an invalid Python identifier.

Returns:

  • op_cost (float) – Operational cost.

  • setup_cost (float) – Setup cost.

cost_eco_model_linker.runner.evaluate_lm_cost(workbook_path: str, scenarios_df: pandas.DataFrame, **factors) → pandas.DataFrame

Evaluate the LM cost model over a year-by-year coral scenario and apply the inventory/replacement model to produce a cost schedule.

For each year in scenarios_df, the required pool count is derived as clip(ceil(number of corals / yield_per_pool), range_lower, range_upper) using the bounds from the LM config. Capex/opex are read back from the spreadsheet each year, and the inventory model is applied across the full time series.

Parameters:

  • workbook_path (str) – Absolute path to the LM Excel workbook including extension (.xlsx).

  • scenarios_df (pd.DataFrame) – Year-by-year coral scenario table with columns year and number of corals. Typically a single rep/intervention slice of iv_yearly_scenarios.csv. Will be sorted by year internally.

  • **factors – Factor name-value pairs to override from config best-point values. Do not pass larval release pools — it is derived from scenarios_df each year.

Returns:

scenarios_df (sorted by year) extended with columns: capex, opex, inventory, new_capex_scale, new_capex_replacement, total_capex, total_capex_opex, ratio, average.

Return type:

pd.DataFrame

cost_eco_model_linker.runner.run_cost_model(workbook_path: str, params_df: pandas.DataFrame, *, model_type: str | None = None, nprocs: int | None = None) → pandas.DataFrame

Evaluate a cost model over a set of parameter combinations.

The model type (production or deployment) and config version are inferred from the workbook filename — e.g. '3.9.1 CA Production Model.xlsx'. Pass model_type explicitly only when the filename does not follow the standard naming convention.

When nprocs is greater than 1, params_df is split into chunks and evaluated in parallel — each worker opens its own temporary workbook copy. Otherwise the whole DataFrame is evaluated serially in a single workbook session.

Columns not present in params_df default to the values currently in the workbook.

Parameters:

  • workbook_path (str) – Absolute path to the Excel workbook including extension (.xlsx).

  • params_df (pd.DataFrame) – Each row is one model evaluation. Column names must be factor names from the relevant config CSV. Only factors to be overridden from workbook defaults need to be included.

  • model_type (str, optional) – "production" or "deployment". Inferred from the filename if not provided.

  • nprocs (int, optional) – Number of parallel worker processes. Values <= 1 run serially. Defaults to serial (None).

Returns:

Input DataFrame with three appended columns: capex, opex, and total_cost.

Return type:

pd.DataFrame

cost_eco_model_linker.runner.sample_joint_factors(nsims: int, seed=None) → tuple[pandas.DataFrame, pandas.DataFrame, pandas.DataFrame, SALib.ProblemSpec]

Generate Sobol’ samples over the combined factor space of all three models (production, deployment, and LM), then slice back into per-model DataFrames.

Building one combined ProblemSpec ensures every row corresponds to the same sample point and that any shared factors are identical across models by construction.

Categorical flooring and discrete value mapping are intentionally not applied here — run_cost_model handles those transformations to avoid double-application.

Parameters:

  • nsims (int) – Desired total number of model evaluations. The base Sobol’ sample count N is derived via get_NK(nsims, n_combined_factors).

  • seed (int or None) – Random seed for reproducibility.

Returns:

  • prod_samples (pd.DataFrame) – Raw Sobol’ samples for the production model.

  • deploy_samples (pd.DataFrame) – Raw Sobol’ samples for the deployment model.

  • lm_samples (pd.DataFrame) – Raw Sobol’ samples for the LM model.

  • combined_sp (ProblemSpec) – The combined ProblemSpec used for sampling.

cost_eco_model_linker.runner.run_joint_cost_models(prod_workbook: str, deploy_workbook: str, lm_workbook: str, prod_samples: pandas.DataFrame, deploy_samples: pandas.DataFrame, lm_samples: pandas.DataFrame, *, nprocs: int = 1) → tuple[pandas.DataFrame, pandas.DataFrame, pandas.DataFrame]

Run production, deployment, and LM cost models against jointly-sampled parameters.

Parameters:

  • prod_workbook (str) – Path to the production model workbook.

  • deploy_workbook (str) – Path to the deployment model workbook.

  • lm_workbook (str) – Path to the LM model workbook.

  • prod_samples (pd.DataFrame) – Raw sample DataFrames as returned by sample_joint_factors.

  • deploy_samples (pd.DataFrame) – Raw sample DataFrames as returned by sample_joint_factors.

  • lm_samples (pd.DataFrame) – Raw sample DataFrames as returned by sample_joint_factors.

  • nprocs (int, optional) – Number of parallel workers. Default 1.

Returns:

prod_results, deploy_results, lm_results – Sample DataFrames with capex, opex, and total_cost columns added.

Return type:

pd.DataFrame

cost_eco_model_linker.runner.sweep_ca(prod_model: str, deploy_model: str, sweep_param: str, search_range, prod_params: dict = None, dep_params: dict = None) → pandas.DataFrame

Sweep a single parameter across the CA production and deployment models.

Parameters:

  • prod_model (str) – Path to production cost model workbook.

  • deploy_model (str) – Path to deployment cost model workbook.

  • sweep_param (str) – Name of the parameter to sweep over.

  • search_range (iterable) – Values to sweep over.

  • prod_params (dict, optional) – Fixed factor overrides for the production model.

  • dep_params (dict, optional) – Fixed factor overrides for the deployment model. Any key also present in prod_params is overwritten by the production value, keeping shared factors (e.g. num_1yoec, coral_yield_1YOEC) consistent.

Returns:

One row per sweep value with columns: search_range, prod_capex, prod_opex, dep_capex, dep_opex, total_cost.

Return type:

pd.DataFrame

cost_eco_model_linker.runner.sweep_lm(lm_model: str, sweep_param: str, search_range, lm_params: dict = None) → pandas.DataFrame

Sweep a single parameter across the LM cost model.

Parameters:

  • lm_model (str) – Path to LM cost model workbook.

  • sweep_param (str) – Name of the parameter to sweep over.

  • search_range (iterable) – Values to sweep over.

  • lm_params (dict, optional) – Fixed factor overrides for the LM model.

Returns:

One row per sweep value with columns: search_range, capex, opex, total_cost.

Return type:

pd.DataFrame