4. VARS-TOOL Package

VARS Sensitivity Anlaysis Framework

The Variogram Analysis of Response Surfaces (VARS) is a powerful sensitivity analysis (SA) method first applied to Earth and Environmental System models.

class DVARS(data_file: str, outvarname: str, ivars_range: Optional[float] = 0.5, phi_max: Optional[float] = 1000000.0, phi0: Optional[float] = 1, correlation_func_type: Optional[str] = 'linear', tol: Optional[float] = 1e-06, report_verbose: Optional[bool] = False)

Bases: object

The Python implementation of the Data Driven Variogram Analysis of Response Surfaces (DVARS) first introduced in Razavi and Gupta (2020) (see [3]_).

simulation_filepd.DataFrame

The file name of file containing input and output data.

outvarnamestr

The name of the output variable to calculate sensitivities for. Note that the output variable must be scalar.

Hjfloat, default: 0.5

The fraction of the total parameter space to integrate over. Note that the linear correlation function only has one hyperparameter, so as the Reference notes it is unable to distinguish variogram effects at varying length scales.

tolfloat, default 1e-6

The convergence tolerance for scipy’s minimize function acting on the negative log likelihood function.

verbosebool, default False

Whether to print diagnostic information.

1

Razavi, S., & Gupta, H. V. (2016). A new framework for comprehensive, robust, and efficient global sensitivity analysis: 1. Theory. Water Resources Research, 52(1), 423-439. doi: 10.1002/2015WR017558

2

Razavi, S., & Gupta, H. V. (2016). A new framework for comprehensive, robust, and efficient global sensitivity analysis: 1. Application. Water Resources Research, 52(1), 423-439. doi: 10.1002/2015WR017559

3

Sheikholeslami, R., & Razavi, S. (2020). A Fresh Look at Variography: Measuring Dependence and Possible Sensitivities Across Geophysical Systems From Any Given Data. Geophysical Research Letters, 47(20). https://doi.org/10.1029/2020gl089829

Razavi, Saman, (2015): algorithm, code in MATALB (c) Blanchard, Cordell, (2022): code in Python 3 Shambaugh, Scott, (2022): code in Python 3

run()

Runs DVARS analysis.

class GVARS(star_centres: ndarray = array([], dtype=float64), num_stars: Optional[int] = 100, parameters: Dict[Union[str, int], Tuple[float, float]] = {}, delta_h: Optional[float] = 0.1, ivars_scales: Optional[Tuple[float, ...]] = (0.1, 0.3, 0.5), model: Optional[Model] = None, seed: Optional[int] = 36201460, sampler: Optional[str] = None, slice_size: Optional[int] = None, bootstrap_flag: Optional[bool] = False, bootstrap_size: Optional[int] = 1000, bootstrap_ci: Optional[float] = 0.9, grouping_flag: Optional[bool] = False, num_grps: Optional[int] = None, report_verbose: Optional[bool] = False, corr_mat: ndarray = array([], dtype=float64), num_dir_samples: int = 50, fictive_mat_flag: Optional[bool] = True, dist_sample_file: Optional[str] = None)

Bases: VARS

The Python implementation of the General Variogram Analysis of Response Surfaces (GVARS), this version can handle correlated factors

Parameters

• star_centres (numpy.array) – contains star centres of the analysis

• num_stars (int, numpy.int32, numpy.int64, defaults to 100) – number of stars to generate

• parameters (dict) – the parameters of the model including lower and upper bounds

• delta_h (float, defaults to 0.1) – the resolution of star samples

• ivars_scales (tuple, defaults to (0.1, 0.3, 0.5)) – the IVARS scales

• model (varstool.Model) – the model used in the sensitivity analysis

• seed (int, numpy.int32, numpy.int64) – the seed number used in generating star centres

• sampler (str) – the type of sampler used to generate star centres

• slice_size (int, numpy.int32, numpy.int64) – slice size for “plhs” sampler

• bootstrap_flag (bool, defaults to False) – flag to bootstrap the sensitivity analysis results

• bootstrap_size (int, defaults to 1000) – the size of bootstrapping experiment

• bootstrap_ci (float, defaults to 0.9) – the condifence interval of boostrapping

• grouping_flag (bool, defaults to False) – flag to conduct grouping of sensitive parameters

• num_grps (int, defaults to None) – the number of groups to categorize parameters

• report_verbose (bool, False) – flag to show the sensitvity analysis progress

• corr_mat (np.ndarray, np.array([])) – correlation matrix

• num_dir_samples (int, 50) – number of directional samples in each star sample

• fictive_mat_flag (bool, False) – flag that sets if correlation matrix it to be used in place of fictive matrix

• dist_sample_file (str, None) – file name that contains custom distribution data

1

Razavi, S., & Gupta, H. V. (2016). A new framework for comprehensive, robust, and efficient global sensitivity analysis: 1. Theory. Water Resources Research, 52(1), 423-439. doi: 10.1002/2015WR017558

2

Razavi, S., & Gupta, H. V. (2016). A new framework for comprehensive, robust, and efficient global sensitivity analysis: 1. Application. Water Resources Research, 52(1), 423-439. doi: 10.1002/2015WR017559

3

Razavi, S., & Do, C. N. (2020). Correlation Effects? A Major but Often Neglected Component in Sensitivity and Uncertainty Analysis. Water Resources Research, 56(3). doi: /10.1029/2019WR025436

Razavi, Saman, (2015): algorithm, code in MATALB (c) Gupta, Hoshin, (2015): algorithm, code in MATLAB (c) Mattot, Shawn, (2019): code in C/++ Do, Nhu, (2020): algorithm, code in MATLAB (c) Keshavarz, Kasra, (2021): code in Python 3 Blanchard, Cordell, (2021): code in Python 3

correlation_plot(param_names: ndarray)

plots the correlation between a pair of parameters, displaying the star points and star centres.

Parameters

param_names (arraylike) – array containing the names of the two parameters you would like plotted

Returns

ax – the axes of the plot

Return type

matplotlib.axes.Axes

factorimportance_plot(logy: bool = False)

plots the ratio of factor importance for IVARS50, VARS-TO, and VARS-ABE

Parameters

logy (boolean) – True if variogram plot is to have a logscale y-axis

Returns

• varax (matplotlib.axes.Axes) – the axes of the variogram plot

• barfig (matplotlib.Figure) – the figure of the bar chart

• barax (matplotlib.axes.Axes) – the axes of the bar chart

generate_star() → DataFrame

Generate GVARS star points

Returns

star_points – dataframe containing star points

Return type

pd.DataFrame

run_offline(model_df)

runs offline version of GVARS program

Parameters

model_df (array_like) – A Pandas Dataframe that contains model ran on generated stars

run_online()

runs online version of GVARS program

property star_centres

returns the star centre samples

property star_points

returns the star point samples.

class Model(func: Optional[Callable] = None, unknown_options: Dict[str, Any] = {})

Bases: object

A wrapper class to contain various models and functions to be fed into VARS and its variations. The models can be called by simply calling the wrapper class itself.

Parameters

• func (Callable) – function of interest

• unknown_options (dict) – a dictionary of options with keys as parameters and values of parameter values.

class TSGVARS(star_centres: ndarray = array([], dtype=float64), num_stars: Optional[int] = 100, parameters: Dict[Union[str, int], Tuple[float, float]] = {}, delta_h: Optional[float] = 0.1, ivars_scales: Optional[Tuple[float, ...]] = (0.1, 0.3, 0.5), model: Optional[Model] = None, seed: Optional[int] = 83426192, sampler: Optional[str] = None, slice_size: Optional[int] = None, bootstrap_flag: Optional[bool] = False, bootstrap_size: Optional[int] = 1000, bootstrap_ci: Optional[float] = 0.9, grouping_flag: Optional[bool] = False, num_grps: Optional[int] = None, report_verbose: Optional[bool] = False, corr_mat: ndarray = array([], dtype=float64), num_dir_samples: int = 50, fictive_mat_flag: Optional[bool] = True, dist_sample_file: Optional[str] = None, func_eval_method: Optional[str] = 'serial', vars_eval_method: Optional[str] = 'serial', vars_chunk_size: Optional[int] = None)

Bases: GVARS

Time-series version of GVARS

generate_star() → DataFrame

Generate TSGVARS star points

Returns

star_points – dataframe containing star points

Return type

pd.DataFrame

run_offline(star_points_eval, star_points: Optional = None)

runs the offline version of TSGVARS program

Parameters

• star_points_eval (array_like) – A Pandas Dataframe that contains model ran on generated stars

• star_points (array_like) – A Pandas Dataframe that contains generated stars

run_online()

runs online version of TS-GVARS

class TSVARS(star_centres=array([], dtype=float64), num_stars: int = 100, parameters: Dict[Union[str, int], Tuple[float, float]] = {}, delta_h: Optional[float] = 0.1, ivars_scales: Optional[Tuple[float, ...]] = (0.1, 0.3, 0.5), model: Optional[Model] = None, seed: Optional[int] = 121430101, sampler: Optional[str] = None, slice_size: Optional[int] = None, bootstrap_flag: Optional[bool] = False, bootstrap_size: Optional[int] = 1000, bootstrap_ci: Optional[int] = 0.9, grouping_flag: Optional[bool] = False, num_grps: Optional[int] = None, report_verbose: Optional[bool] = False, func_eval_method: Optional[str] = 'serial', vars_eval_method: Optional[str] = 'serial', vars_chunk_size: Optional[int] = None)

Bases: VARS

Time-series version of VARS

generate_star() → DataFrame

Generate TSVARS star points

Returns

star_points – dataframe containing star points

Return type

pd.DataFrame

run_offline(star_points_eval, star_points: Optional = None)

runs the offline version of TSVARS program

Parameters

• star_points_eval (array_like) – A Pandas Dataframe that contains model ran on generated stars

• star_points (array_like) – A Pandas Dataframe that contains the generated stars

run_online()

runs online version of TS-VARS

class VARS(star_centres: ndarray = array([], dtype=float64), num_stars: Optional[int] = 100, parameters: Dict[Union[str, int], Tuple[float, float]] = {}, delta_h: Optional[float] = 0.1, ivars_scales: Optional[Tuple[float, ...]] = (0.1, 0.3, 0.5), model: Optional[Model] = None, seed: Optional[int] = 106901406, sampler: Optional[str] = None, slice_size: Optional[int] = None, bootstrap_flag: Optional[bool] = False, bootstrap_size: Optional[int] = 1000, bootstrap_ci: Optional[float] = 0.9, grouping_flag: Optional[bool] = False, num_grps: Optional[int] = None, report_verbose: Optional[bool] = False)

Bases: object

The Python implementation of the Variogram Analysis of Response Surfaces (VARS) first introduced in Razavi and Gupta (2015) (see [1]_ and [2]_).

Parameters

• star_centres (numpy.array) – contains star centres of the analysis

• num_stars (int, numpy.int32, numpy.int64, defaults to 100) – number of stars to generate

• parameters (dict) – the parameters of the model including lower and upper bounds

• delta_h (float, defaults to 0.1) – the resolution of star samples

• ivars_scales (tuple, defaults to (0.1, 0.3, 0.5)) – the IVARS scales

• model (varstool.Model) – the model used in the sensitivity analysis

• seed (int, numpy.int32, numpy.int64) – the seed number used in generating star centres

• sampler (str) – the type of sampler used to generate star centres

• slice_size (int, numpy.int32, numpy.int64) – slice size for “plhs” sampler

• bootstrap_flag (bool, defaults to False) – flag to bootstrap the sensitivity analysis results

• bootstrap_size (int, defaults to 1000) – the size of bootstrapping experiment

• bootstrap_ci (float, defaults to 0.9) – the condifence interval of boostrapping

• grouping_flag (bool, defaults to False) – flag to conduct grouping of sensitive parameters

• num_grps (int, defaults to None) – the number of groups to categorize parameters

• report_verbose (bool, False) – flag to show the sensitvity analysis progress

1

Razavi, S., & Gupta, H. V. (2016). A new framework for comprehensive, robust, and efficient global sensitivity analysis: 1. Theory. Water Resources Research, 52(1), 423-439. doi: 10.1002/2015WR017558

2

Razavi, S., & Gupta, H. V. (2016). A new framework for comprehensive, robust, and efficient global sensitivity analysis: 1. Application. Water Resources Research, 52(1), 423-439. doi: 10.1002/2015WR017559

Razavi, Saman, (2015): algorithm, code in MATALB (c) Gupta, Hoshin, (2015): algorithm, code in MATLAB (c) Mattot, Shawn, (2019): code in C/++ Keshavarz, Kasra, (2021): code in Python 3 Blanchard, Cordell, (2021): code in Python 3

correlation_plot(param_names: ndarray)

plots the correlation between a pair of parameters, displaying the star points and star centres.

Parameters

param_names (arraylike) – array containing the names of the two parameters you would like plotted

Returns

ax – the axes of the plot

Return type

matplotlib.axes.Axes

factorimportance_plot(logy: bool = False)

plots the ratio of factor importance for IVARS50, VARS-TO, and VARS-ABE

Parameters

logy (boolean) – True if variogram plot is to have a logscale y-axis

Returns

• varax (matplotlib.axes.Axes) – the axes of the variogram plot

• barfig (matplotlib.Figure) – the figure of the bar chart

• barax (matplotlib.axes.Axes) – the axes of the bar chart

generate_star() → DataFrame

Generate VARS star points

Returns

star_points – dataframe containing star points

Return type

pd.DataFrame

run_offline(model_df)

runs the offline version of VARS program

Parameters

model_df (array_like) – A Pandas Dataframe that contains model ran on generated stars

run_online()

runs the online version of the VARS program

property star_centres

returns the star centre samples

property star_points

returns the star point samples

Subpackages

• varstool.example_models package
• varstool.sensitivity_analysis package
  • vars_functions
  • gvars_functions
  • tsvars_functions
    • dvars_functions
• varstool.sampling package
  • general sampling functions
  • generalized star-based (gSTAR) sampling functions
  • STAR sampling (starvars) functions