cost_eco_model_linker.sampling

Attributes

THIS_DIR

DEFAULT_PROD_VER

DEFAULT_DEPLOY_VER

DEFAULT_LM_VER

Functions

get_NK(→ tuple[int, int])

Calculate the base Sobol' sample count N given a desired total number of

evaluate_spreadsheet(→ tuple[float, float])

Set input cells, trigger recalculation, and read back capex and opex.

calculate_deployment_cost(wb, model_spec, factors)

Calculates set up and operational costs in the deployment cost model (wb), given a set of parameters to sample.

calculate_production_cost(wb, factor_spec, factors)

Calculates set up and operational costs in the production cost model (wb), given a set of parameters to sample.

load_config()

Load configuration files for model sampling (production, deployment, and LM).

load_internal_config(fp)

Load internal config for model sampling

problem_spec(cost_type)

Create a problem specification for sampling cost models using SALib.

convert_factor_types(factors_df, is_cat)

SALib samples floats, so convert categorical variables to integers by taking the ceiling.

apply_discrete_mapping(factors_df, model_spec)

Map sampled integer indices back to their actual discrete values.

collect_production_costs(xlapp, wb, wb_path, ...[, ...])

Run the production cost model.

collect_deployment_costs(xlapp, wb, wb_path, ...[, ...])

Run the deployment cost model.

calculate_lm_cost(wb, factor_spec, factors)

Calculates setup and operational costs in the LM (Larval Methods) cost model.

collect_lm_costs(xlapp, wb, wb_path, cost_factors, ...)

Run the LM cost model.

run_lm_model(cost_model, nsims[, nprocs])

Generate Sobol' samples for the LM model and run.

run_deployment_model(cost_model, nsims[, nprocs])

Generate Sobol' samples for the deployment model and run.

run_production_model(cost_model, nsims[, nprocs])

Generate Sobol' samples for the production model and run.

extract_sa_results(sp[, fig_path])

Run PAWN sensitivity analysis on cost model results and save figures.

Module Contents

cost_eco_model_linker.sampling.THIS_DIR
cost_eco_model_linker.sampling.DEFAULT_PROD_VER = '3.9.1'
cost_eco_model_linker.sampling.DEFAULT_DEPLOY_VER = '3.9.0'
cost_eco_model_linker.sampling.DEFAULT_LM_VER = '3.9.6'
cost_eco_model_linker.sampling.get_NK(nsims: int, n_factors: int, calc_second_order: bool = False) → tuple[int, int]

Calculate the base Sobol’ sample count N given a desired total number of model evaluations and the number of input factors.

SALib’s Saltelli sampler produces N * K samples where: - K = 2 * n_factors + 2 when calc_second_order=True - K = n_factors + 2 when calc_second_order=False

Returns the smallest N such that N * K >= nsims.

Parameters:

  • nsims (int) – Desired total number of model evaluations.

  • n_factors (int) – Number of input factors (excluding output columns).

  • calc_second_order (bool, optional) – Whether second-order indices will be calculated. Must match the value passed to sample_sobol. Default False.

Returns:

  • N (int) – Base sample count to pass to sample_sobol.

  • K (int) – Saltelli multiplier.

cost_eco_model_linker.sampling.evaluate_spreadsheet(wb, model_spec, params) → tuple[float, float]

Set input cells, trigger recalculation, and read back capex and opex.

This is the inner function for both cost models. All model-specific parameter transformations (yield adjustment, reef name resolution, vessel type switching) must be applied to params before calling this function.

Parameters:

  • wb (Workbook) – Open Excel workbook.

  • model_spec (DataFrame) – Factor specification with columns: factor_names, sheet, cell_pos.

  • params (Series) – Fully-resolved parameter values indexed by factor_names.

Returns:

  • capex (float)

  • opex (float)

cost_eco_model_linker.sampling.calculate_deployment_cost(wb, model_spec, factors)

Calculates set up and operational costs in the deployment cost model (wb), given a set of parameters to sample.

Parameters:

  • wb (Workbook) – The cost model as an excel workbook

  • model_spec (DataFrame) – The cost model specification, detailing where cells are in the spreadsheet

  • factors (DataFrameRow) – Factor values to run cost model with

Returns:

  • capex (float) – Setup cost (CAPEX)

  • opex (float) – Operational cost (OPEX)

cost_eco_model_linker.sampling.calculate_production_cost(wb, factor_spec, factors)

Calculates set up and operational costs in the production cost model (wb), given a set of parameters to sample.

Parameters:

  • wb (Workbook) – The cost model as an excel workbook

  • factor_spec (DataFrame) – Factor specification, as loaded from the config.csv

  • factors (DataFrameRow) – Factor values to run model with

Returns:

  • capex (float) – Setup cost (CAPEX)

  • opex (float) – Operational cost (OPEX)

cost_eco_model_linker.sampling.load_config()

Load configuration files for model sampling (production, deployment, and LM).

cost_eco_model_linker.sampling.load_internal_config(fp)

Load internal config for model sampling

Parameters:

fp (str) – Filename of config file within the package structure

cost_eco_model_linker.sampling.problem_spec(cost_type)

Create a problem specification for sampling cost models using SALib.

Parameters:

  • cost_type (str) – String specifying cost model type, “production_params” or “deployment_params”

  • config_filepath (str) – String specifying filepath of config file, default is the default package config file

Returns:

  • sp (dict) – ProblemSpec for sampling with SALib

  • model_spec (dataframe) – factor specification, as loaded from the config.csv

cost_eco_model_linker.sampling.convert_factor_types(factors_df, is_cat)

SALib samples floats, so convert categorical variables to integers by taking the ceiling.

Parameters:

  • factors_df (dataframe) – A dataframe of sampled factors

  • is_cat (list{bool}) – Boolian vector specifian whether each factor is categorical

Returns:

factors_df

Return type:

Updated sampled factor dataframe with categorical factors as integers

cost_eco_model_linker.sampling.apply_discrete_mapping(factors_df, model_spec)

Map sampled integer indices back to their actual discrete values. Only applies to factors with a discrete_values entry in model_spec. Factors marked as is_cat without discrete_values are already handled by the flooring trick in convert_factor_types.

Parameters:

  • factors_df (dataframe) – A dataframe of sampled factors

  • model_spec (dataframe) – Factor specification, as loaded from the config CSV

Returns:

factors_df

Return type:

Updated sampled factor dataframe with discrete mappings applied

Raises:

ValueError – If the min/max of discrete_values does not match range_lower/range_upper

cost_eco_model_linker.sampling.collect_production_costs(xlapp, wb, wb_path, cost_factors, factor_spec, workbook_session=None)

Run the production cost model.

Parameters:

  • xlapp – Excel application instance

  • wb – Open Excel workbook

  • wb_path (str) – Path to the workbook file

  • cost_factors (dataframe) – Dataframe of factors to input in the cost model

  • factor_spec (dataframe) – Factor specification, as loaded from the config.csv

  • workbook_session (WorkbookSession, optional) – A session object for caching and seeding optimization.

Returns:

  • wb – Updated workbook reference (may differ from input if resets occurred internally).

  • cost_factors (dataframe) – Updated sampled factor dataframe with costs added

cost_eco_model_linker.sampling.collect_deployment_costs(xlapp, wb, wb_path, cost_factors, factor_spec, workbook_session=None)

Run the deployment cost model.

Parameters:

  • xlapp – Excel application instance

  • wb – Open Excel workbook

  • wb_path (str) – Path to the workbook file

  • cost_factors (dataframe) – Dataframe of factors to input in the cost model

  • factor_spec (dataframe) – Factor specification, as loaded from the config.csv

  • workbook_session (WorkbookSession, optional) – A session object for caching and seeding optimization.

Returns:

  • wb – Updated workbook reference (may differ from input if resets occurred internally).

  • cost_factors (dataframe) – Updated sampled factor dataframe with costs added

cost_eco_model_linker.sampling.calculate_lm_cost(wb, factor_spec, factors)

Calculates setup and operational costs in the LM (Larval Methods) cost model.

Parameters:

  • wb (Workbook) – Open Excel workbook.

  • factor_spec (DataFrame) – Factor specification, as loaded from the config CSV.

  • factors (DataFrameRow) – Factor values to run model with.

Returns:

  • capex (float)

  • opex (float)

cost_eco_model_linker.sampling.collect_lm_costs(xlapp, wb, wb_path, cost_factors, factor_spec, workbook_session=None)

Run the LM cost model.

Parameters:

  • xlapp – Excel application instance.

  • wb – Open Excel workbook.

  • wb_path (str) – Path to the workbook file.

  • cost_factors (DataFrame) – Dataframe of factors to input in the cost model.

  • factor_spec (DataFrame) – Factor specification, as loaded from the config CSV.

  • workbook_session (WorkbookSession, optional) – A session object for caching and seeding optimization.

Returns:

  • wb – Updated workbook reference (may differ from input if resets occurred internally).

  • cost_factors (DataFrame) – Updated sampled factor dataframe with costs added.

cost_eco_model_linker.sampling.run_lm_model(cost_model: str, nsims: int, nprocs: int = 1)

Generate Sobol’ samples for the LM model and run.

Parameters:

  • cost_model (str) – Path to the LM cost model workbook, including extension (.xlsx).

  • nsims (int) – Desired total number of model evaluations.

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

Return type:

SALib ProblemSpec with cost_model_results added as a field.

cost_eco_model_linker.sampling.run_deployment_model(cost_model: str, nsims: int, nprocs: int = 1)

Generate Sobol’ samples for the deployment model and run.

Parameters:

  • cost_model (str) – Path to cost (spreadsheet) model

  • nsims (int) – Desired total number of model evaluations. The base Sobol’ sample count N is derived via get_NK(nsims, n_factors), giving N*(2D+2) actual evaluations (the closest multiple >= nsims).

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

Return type:

SALib ProblemSpec with cost_model_results added as a field.

cost_eco_model_linker.sampling.run_production_model(cost_model: str, nsims: int, nprocs: int = 1)

Generate Sobol’ samples for the production model and run.

Parameters:

  • cost_model (str) – Path to cost (spreadsheet) model, including extension (.xlsx)

  • nsims (int) – Desired total number of model evaluations. The base Sobol’ sample count N is derived via get_NK(nsims, n_factors), giving N*(2D+2) actual evaluations (the closest multiple >= nsims).

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

Return type:

SALib ProblemSpec with cost_model_results added as a field.

cost_eco_model_linker.sampling.extract_sa_results(sp: SALib.ProblemSpec, fig_path: str = './figs/')

Run PAWN sensitivity analysis on cost model results and save figures.

Parameters:

  • sp (ProblemSpec) – Must have sp["cost_model_results"] set to a DataFrame with columns matching sp["names"] plus "capex" and "opex". Use sp["cost_model_results"] = results_df to attach results from run_joint_cost_models before calling this function.

  • fig_path (str) – Directory where figures are saved.