:py:mod:`metacast.sensitivity_analyses` ======================================= .. py:module:: metacast.sensitivity_analyses .. autoapi-nested-parse:: Creation: Author: Martin Grunnill Date: 2024-02-09 Description: Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 asses_lh_sample_size/index.rst lhs_and_prcc/index.rst Package Contents ---------------- Functions ~~~~~~~~~ .. autoapisummary:: metacast.sensitivity_analyses.lhs_prcc metacast.sensitivity_analyses.calculate_prcc metacast.sensitivity_analyses.determine_lh_sample_size .. py:function:: lhs_prcc(parameters_df, sample_size, model_run_method, client=None, lhs_obj=None, other_samples_to_repeat=None, **kwargs) Generate a Latin Hypercube sample, run model with sample and calculate PRCC for sampled parameters. Latin Hypercube Sampling with Partial Rank Correlation Coefficients (PRCCS) can be used to evaluate sensitivity of a model to a parameter[1]. Note currently only supports uniform distribution. :param parameters_df: DataFrame outlining the boundaries for each parameter. Must contain fields 'Lower Bound' and 'Upper Bound'. The name of the parameters is assumed to be in the index of the DataFrame. Alternatively, may be a dictionary that maps parameter names to percentage-point (inverse-CDF) functions. :type parameters_df: pandas.DataFrame or dictionary :param sample_size: Sample size of Latin Hypercube. :type sample_size: int :param model_run_method: Method of running model's simulations. Must accept parameters as a single dictionary. Must output dictionary of input parameters and model results. :type model_run_method: function :param client: Dask client for running simulations in parallel. If not given simulations are run serially with a tqdm progress bar. :type client: dask.distributed.Client (default None) :param lhs_obj: Pre-initialised Latin Hypercube sample generator. If not provided one is generated by within this function. :type lhs_obj: scipy.stats.qmc.LatinHypercube, optional :param other_samples_to_repeat: Samples to resampled and merged with LH samples. :type other_samples_to_repeat: pandas.DataFrame :param kwargs: Key word arguments to be passed to model_run_method. :returns: * **results_df** (*pandas.DataFrame*) -- Results of simulations preceded by parameters used in simulations. * **prccs** (*pandas.DataFrame*) -- PRCC summary of the model's sensitivity to its parameters. .. rubric:: References [1] Marino, S., Hogue, I. B., Ray, C. J., & Kirschner, D. E. (2008). A methodology for performing global uncertainty and sensitivity analysis in systems biology. In Journal of Theoretical Biology (Vol. 254, Issue 1, pp. 178–196). https://doi.org/10.1016/j.jtbi.2008.04.011 .. py:function:: calculate_prcc(results_and_sample_df, parameter, output, covariables, method='spearman') Calculate Partial Correlation Coefficient PCC (default Rank 'Spearman' PRCC). A wrapper for pingouin.partial_corr. Partial Rank Correlation Coefficients (PRCCS) can be used to evaluate sensitivity of a model to a parameter[1]. :param results_and_sample_df: DataFrame of results and parameters for calculating PCC. :type results_and_sample_df: pandas.DataFrame :param parameter: Parameter for which PCC will be calculated. :type parameter: string :param output: Model output for which PCC will be calculated. :type output: string :param covariables: Parameters whose effects will be discounted. :type covariables: list of strings :param method: Form of PCC see documentation of pingouin.partial_corr. :type method: string, default 'spearman' (Rank correlations) :returns: Partial Corelation Coefficient of parameter and output. :rtype: pandas.DataFrame .. rubric:: References [1] Marino, S., Hogue, I. B., Ray, C. J., & Kirschner, D. E. (2008). A methodology for performing global uncertainty and sensitivity analysis in systems biology. In Journal of Theoretical Biology (Vol. 254, Issue 1, pp. 178–196). https://doi.org/10.1016/j.jtbi.2008.04.011 .. py:function:: determine_lh_sample_size(parameters_df, model_run_method, start_n, repeats_per_n, std_aim, LHS_PRCC_method, save_dir, attempts_to_make=float('inf'), n_increase_addition=None, n_increase_multiple=None, y0=None, other_samples_to_repeat=None, max_workers=None) Assess if a Latin-Hypercube (LH) sample size is reasonable. Method is as follows: 1. For a given LH sample size draw and simulate a model through repeats_per_n number of LHSs. 2. Determine standard deviation in PRCCs. If any PRCC is greater than std_aim increase LH sample size by either addittion (n_increase_addition) or multiplication (n_increase_multiple) and return to 1. :param parameters_df: DataFrame outlining the boundaries for each parameter. Must contain fields 'Lower Bound' and 'Upper Bound'. Name of the parameters is assumed to be in the index. :type parameters_df: pd.DataFrame :param model_run_method: Method for simulating model. :type model_run_method: function :param start_n: Suggested sample size to start from. :type start_n: int :param repeats_per_n: Number of repeats per sample size. :type repeats_per_n: int :param std_aim: Standard deviation goal. :type std_aim: float :param LHS_PRCC_method: Method for drawing LHs simulating models through LHs and determining PRCC. :type LHS_PRCC_method: function :param save_dir: Directory for saving results. :type save_dir: string :param attempts_to_make: Number of attempts to make. :type attempts_to_make: int :param n_increase_addition: Increase in sample size, by addition, to be made if standard deviation in any paramters PRCC is greater than std_aim. :type n_increase_addition: int, mutually exclusive with n_increase_multiple :param n_increase_multiple: Increase in sample size, by multiplication, to be made if standard deviation in any paramters PRCC is greater than std_aim. :type n_increase_multiple: int, mutually exclusive with n_increase_addition :param y0: Intial values of state variables. :type y0: numpy.array, optional :param other_samples_to_repeat: Samples to resampled and merged with LH samples. :type other_samples_to_repeat: pandas.DataFrame :param max_workers: Number workers if LHS_PRCC method is parallelized. :type max_workers: int, optional :returns: Sample size assessed as being reasonable. :rtype: int