sampling_functions
==================

.. py:module:: sampling_functions


Functions
---------

.. autoapisummary::

   sampling_functions.calculate_deployment_cost
   sampling_functions.calculate_production_cost
   sampling_functions.load_config
   sampling_functions.problem_spec
   sampling_functions.convert_factor_types
   sampling_functions._sample_cost
   sampling_functions.sample_deployment_cost
   sampling_functions.sample_production_cost
   sampling_functions.cost_sensitivity_analysis


Module Contents
---------------

.. py:function:: calculate_deployment_cost(wb, factor_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
       factor_spec : dataframe
           The factor specification, as loaded from the config.csv
       factors : dataframerow
           Row of a pandas dataframe with factors to sample

   Returns
   -------
       Cost: float
           Operational cost
       setupCost: float
           Setup cost


.. py:function:: 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
           Row of a pandas dataframe with factors to sample

   Returns
   -------
       Cost: float
           Operational cost
       setupCost: float
           Setup cost


.. py:function:: load_config(config_filepath='config.csv')

   Load configuration file for model sampling

   Parameters
   ----------
       config_filepath : str
           String specifying filepath of config file, default is the default package config file


.. py:function:: problem_spec(cost_type, config_filepath='config.csv')

   Create a problem specification for sampling 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
       factor_spec : dataframe
           factor specification, as loaded from the config.csv


.. py:function:: 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: Updated sampled factor dataframe with categorical factors as integers


.. py:function:: _sample_cost(wb_file_path, factors_df, factor_spec, calculate_cost)

   Sample a cost model.

   Parameters
   ----------
       wb_file_path : str
           Filepath to a cost model as an excel workbook
       factors_df : dataframe
           Dataframe of factors to input in the cost model
       factor_spec : dataframe
           factor specification, as loaded from the config.csv
       calculate_cost: function
           Function to use to sample cost

   Returns
   -------
       factors_df : dataframe
           Updated sampled factor dataframe with costs added


.. py:function:: sample_deployment_cost(wb_file_path, factors_df, factor_spec)

   Sample the deployment cost model.

   Parameters
   ----------
       wb_file_path : str
           Filepath to a cost model as an excel workbook
       factors_df : dataframe
           Dataframe of factors to input in the cost model
       factor_spec : dataframe
           factor specification, as loaded from the config.csv

   Returns
   -------
       factors_df : dataframe
           Updated sampled factor dataframe with costs added


.. py:function:: sample_production_cost(wb_file_path, factors_df, factor_spec)

   Sample the production cost model.

   Parameters
   ----------
       wb_file_path : Workbook file path
           A cost model as an excel workbook
       factors_df : dataframe
           Dataframe of factors to input in the cost model
       factor_spec : dataframe
           Factor specification, as loaded from the config.csv

   Returns
   -------
       factors_df : dataframe
           Updated sampled factor dataframe with costs added


.. py:function:: cost_sensitivity_analysis(samples_fn, cost_type, figures_path='.\\src\\figures\\')

   Perform a sensitvity analysis with costs as output from a set of samples.

   Parameters
   ----------
       samples_fn : str
           Filename/path of the samples.
       cost_type : str
           "production" or "deployment".
       figures_path : str
           Path to save figures from the sensitvity analysis.