:py:mod:`metacast.sensitivity_analyses.lhs_and_prcc` ==================================================== .. py:module:: metacast.sensitivity_analyses.lhs_and_prcc .. autoapi-nested-parse:: Creation: Author: Martin Grunnill Date: 2024-03-08 Description: Generate Latin-Hypercube Sample (LHS), run simulations and calculate Partial Correlation Coefficients (PRCCs). For a description of LHS and PRCCs use in model sensitivity analyses see: 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 .. rubric:: Notes Serial processing of LHS can be slow. but parallel processing of LHS can take up a lot of computing resources. Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: metacast.sensitivity_analyses.lhs_and_prcc._format_sample metacast.sensitivity_analyses.lhs_and_prcc.calculate_prcc metacast.sensitivity_analyses.lhs_and_prcc.lhs_prcc metacast.sensitivity_analyses.lhs_and_prcc.run_samples_serially metacast.sensitivity_analyses.lhs_and_prcc.run_samples_in_parallel .. py:function:: _format_sample(parameters_df, LH_samples, other_samples_to_repeat=None) Formats Latin Hypercube sample generated by scipy.stats.qmc. Scales LH_samples in with boundaries outlined in parameters_df. :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. Alternatively, may be a dictionary that maps parameter names to percentage-point (inverse-CDF) functions. :type parameters_df: pd.DataFrame or dictionary :param LH_samples: Output from scipy.stats.qmc.LatinHypercube. :type LH_samples: numpy.array :param other_samples_to_repeat: Samples to resampled and merged with LH samples. :type other_samples_to_repeat: pandas.DataFrame :returns: * **samples_df** (*pandas.Dataframe*) -- Fully formatted samples. * **parameters_sampled** (*list*) -- A list of samples being sampled. .. 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:: 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:: run_samples_serially(parameters_df, model_run_method, **kwargs) .. py:function:: run_samples_in_parallel(parameters_df, model_run_method, client, **kwargs) Runs model simulations using parameters in sample_df using parallel processing. :param parameters_df: Parameter samples being run. Column fields are parameters. :type parameters_df: pandas.Dataframe :param model_run_method: Method of running model's simulations. Must accept parameters as a single dictionary in the first argument. Must output dictionary of input parameters and model results. :type model_run_method: function :param kwargs: Key word arguments to pass to model_run_method. :rtype: If return_focused_results is True a pandas DataFrame of results is returned.