Capabilities Documentation

plotting docu

probabilistic.capabilities.plotting.initiate_plot_settings()

Initialize default plotting settings.

Returns:

A tuple containing two itertools.cycle objects: - line_cycler: cycle through line styles. - color_cycler: cycle through colors.

Return type:

tuple

probabilistic.capabilities.plotting.plot_deterministic_parameter_value(value, variable_name)

Plot a deterministic parameter value as a single point on the x-axis.

Parameters:

  • value (float) – The deterministic value to be plotted.

  • variable_name (str) – Name of the variable to be displayed on the x-axis.

probabilistic.capabilities.plotting.plot_distribution_pdf(distribution, variable_name, plot_limits=False)

Plot the probability density function (PDF) of a distribution.

Parameters:

  • distribution (object) – A distribution object with .mean(), .std(), and .pdf() methods (e.g., from scipy.stats).

  • variable_name (str) – Name of the variable to be displayed on the x-axis.

  • plot_limits (tuple of float, optional) – Tuple specifying (min, max) x-axis limits for plotting. If False (default), limits are set to ±3 standard deviations from the mean.

probabilistic.capabilities.plotting.plot_sample_cdf(samples: array, variable_name: str, percentiles: list = False, **kwargs)

Plot the cumulative distribution function (CDF) from a set of samples.

Parameters:

  • samples (np.array) – Data to be plotted

  • variable_name (str) – Name of data to be plotted

  • percentiles (list) – Percentiles to include on plot

  • **kwargs (dict) – Additional histogram function inputs

probabilistic.capabilities.plotting.plot_sample_histogram(samples: array, variable_name: str, percentiles: list = False, save_fig=False, filepath='', **kwargs)

Plot a histogram of sample data with optional percentile annotations.

Parameters:

  • samples (np.array) – Data to be plotted

  • variable_name (str) – Name of data to be plotted

  • percentiles (list) – Percentiles to include on plot

  • save_fig (bool, default False) – If True, saves the figure to the specified filepath.

  • filepath (str, default "") – Path to save the figure if save_fig is True.

  • kwargs (dict) – Additional histogram function inputs

probabilistic.capabilities.plotting.plot_scatter_matrix(data_dict, density=False)

Generate a scatter matrix plot for visualizing relationships between multiple variables.

Parameters:

  • data_dict (dict) – Dictionary where keys are parameter names and values are lists or arrays of samples.

  • density (bool) – If True, histograms on the diagonal show probability densities instead of counts. Default is False.

probabilistic.capabilities.plotting.plot_time_series_parameter_value(value, variable_name)

Plot a deterministic value as a time series.

Parameters:

  • value (array-like) – Series of values to plot over time.

  • variable_name (str) – Name of the variable to be displayed on the y-axis.

sampling docu

class probabilistic.capabilities.sampling.BoundingStudy(number_of_aleatory_samples: int, number_of_epistemic_samples: int, random_state)

A sensitivity study where each variable is sampled at its bounding percentiles, holding all other variables at their nominal values.

Inherits all attributes from OneAtATimeSensitivityStudy and UncertaintyStudy.
add_sensitivity_samples_to_sample_sheet(aleatory_samples, epistemic_samples)

Add bounding sensitivity samples to the sample sheet.

Parameters:

  • aleatory_samples (dict) – Dictionary of aleatory variable samples (2 per variable).

  • epistemic_samples (dict) – Dictionary of epistemic variable samples (2 per variable).

Returns:

The populated sample sheet for the study.

Return type:

dict

determine_total_sample_size()

Compute total sample size for bounding sensitivity study.

generate_cdf_samples(_)

Generate bounding percentile values for sampling. Ignores input and returns the lower and upper CDF percentiles.

Parameters:

_ (any) – Ignored input.

Returns:

Array with two values: [0.01, 0.99].

Return type:

np.ndarray

relevant_error_checks()

Ensures that all variables have unique names across aleatory, epistemic, and deterministic groups.

class probabilistic.capabilities.sampling.LHSStudy(number_of_aleatory_samples: int, number_of_epistemic_samples: int, random_state)

Uses LHS to efficiently sample input space of uncertain variables.

Inherits all attributes from UncertaintyStudy.
collect_variables(variable_distribution_dict, number_of_samples)

Collect variable samples for LHS study.

Parameters:

  • variable_distribution_dict (dict) – Dictionary of variable names and distributions.

  • number_of_samples (int) – Number of LHS samples to generate.

Returns:

Dictionary of variable samples.

Return type:

dict

create_variable_sample_sheet()

Create sample sheet for LHS study.

Returns:

Completed sample sheet.

Return type:

dict

relevant_error_checks()

Perform error checks on specified study details.

class probabilistic.capabilities.sampling.OneAtATimeSensitivityStudy(number_of_aleatory_samples: int, number_of_epistemic_samples: int, random_state)

Varies one variable at a time across its distribution while holding others at their nominal values.

Inherits all attributes from SensitivityStudy and UncertaintyStudy.
add_sensitivity_samples_to_sample_sheet(aleatory_samples, epistemic_samples)

Add sensitivity study samples to sample sheet for sampling based sensitivity study.

Parameters:

  • aleatory_samples (dict) – Sampled aleatory variable values.

  • epistemic_samples (dict) – Sampled epistemic variable values.

Returns:

Populated sample sheet.

Return type:

dict

collect_variables(variable_distribution_dict, number_of_samples)

Collect samples for uncertain variables for sampling based sensitivity study.

Parameters:

  • variable_distribution_dict (dict) – Dictionary of variable names and distributions.

  • number_of_samples (int) – Number of CDF-based samples to generate.

Returns:

Dictionary of variable samples.

Return type:

dict

create_variable_sample_sheet()

Create sample sheet for one-at-a-time sensitivity study.

Returns:

Completed sample sheet.

Return type:

dict

determine_total_sample_size()

Determine the total sample size of the study.

generate_cdf_samples(number_of_samples)

Specify percentiles sampled from CDF.

Parameters:

number_of_samples (int) – Number of percentile points to generate.

Returns:

Array of percentiles.

Return type:

np.ndarray

relevant_error_checks()

Perform error checks on specified study details. Checks for unique variable names and consistency between distributions and sample sizes.

class probabilistic.capabilities.sampling.RandomStudy(number_of_aleatory_samples: int, number_of_epistemic_samples: int, random_state)

Random Sampling Uncertainty Study Class

Inherits all attributes from UncertaintyStudy.
collect_variables(variable_distribution_dict, number_of_samples)

Collect samples for variables using random sampling.

Parameters:

  • variable_distribution_dict (dict) – Dictionary of variable names to distribution objects.

  • number_of_samples (int) – Number of samples to generate.

Returns:

Dictionary of samples by variable name.

Return type:

dict

create_variable_sample_sheet()

Create sample sheet and add samples for random sampling study.

Returns:

Completed sample sheet.

Return type:

dict

relevant_error_checks()

Perform error checks on specified study details.

class probabilistic.capabilities.sampling.SensitivityStudy(number_of_aleatory_samples: int, number_of_epistemic_samples: int, random_state)

Implement base functionality for sampling-based sensitivity analyses.

Inherits all attributes from UncertaintyStudy.
relevant_error_checks()

Ensures all variable names are unique across aleatory, epistemic, and deterministic categories.

class probabilistic.capabilities.sampling.UncertaintyStudy(number_of_aleatory_samples: int, number_of_epistemic_samples: int, random_state)

Manages uncertain and deterministic variables, handles sample generation, and stores variable samples for downstream probabilistic analysis.

number_of_aleatory_samples

Number of samples to generate for aleatory (random) uncertainty.

Type:

int

number_of_epistemic_samples

Number of samples to generate for epistemic (knowledge-based) uncertainty.

Type:

int

random_state

Random seed or random number generator instance for reproducibility.

Type:

int, np.random.Generator, or None

aleatory_variables

Dictionary holding aleatory variable definitions.

Type:

dict

epistemic_variables

Dictionary holding epistemic variable definitions.

Type:

dict

deterministic_variables

Dictionary holding deterministic variable definitions.

Type:

dict

sample_sheet

Dictionary containing sampled values for all variables.

Type:

dict

nominal_sample_sheet

Dictionary containing nominal values for all variables.

Type:

dict

total_sample_size

Total number of samples across uncertainty types, if calculated.

Type:

int or None

add_aleatory_samples_to_sample_sheet(samples)

Add aleatory variable samples to uncertainty study sample sheet.

Parameters:

samples (dict) – Dictionary mapping variable names to sample arrays.

add_deterministic_samples_to_sample_sheet(parameter, sample_size)

Add deterministic samples to sample sheet.

Parameters:

  • parameter (dict) – Dictionary of deterministic variable names and objects.

  • sample_size (int) – Total number of samples to generate per variable.

add_deterministic_variables(deterministic_set)

Add deterministic variables to the study.

Parameters:

deterministic_set (list of DeterministicCharacterization) – List of deterministic variables to add.

add_epistemic_samples_to_sample_sheet(samples)

Add epistemic variable samples to uncertainty study sample sheet.

Parameters:

samples (dict) – Dictionary mapping variable names to sample arrays.

add_nominal_values_to_sample_sheet(nominal_values)

Add nominal values to sample sheet for generic sampling study.

Parameters:

nominal_values (dict) – Dictionary of nominal values by variable name.

add_probabilistic_variables(distribution_set)

Add probabilistic variables to the study.

Parameters:

distribution_set (list) – List of uncertain variables with specified type.

Raises:

ValueError – If a variable has an invalid uncertainty type.

static add_variable_name(variable_distribution, location)

Ensure that variable names are unique within a given category.

Parameters:
Raises:

ValueError – If a variable with the same name already exists.

add_variables(input_parameters)

Add uncertain and deterministic variables to the study.

Parameters:

input_parameters (dict) – Dictionary of parameter names and associated uncertainty or deterministic characterization.

Raises:

ValueError – If a parameter is not associated with a recognized characterization.

static calc_number_of_variables(variable_dict)

Calculate the number of variables in a dictionary.

Parameters:

variable_dict (dict) – Dictionary of variable definitions.

Returns:

Number of entries in the dictionary.

Return type:

int

calc_total_number_of_variables()

Determine total number of uncertain variables in uncertainty study.

Returns:

Total number of aleatory and epistemic variables.

Return type:

int

static collect_variable_nominal_values(variable_dict)

Collect nominal values for a set of variables.

Parameters:

variable_dict (dict) – Dictionary of variables with nominal values.

Returns:

Mapping of variable names to their nominal values.

Return type:

dict

create_variable_nominal_sheet()

Create a nominal sample sheet from all variable types.

Returns:

Dictionary of nominal sample values.

Return type:

dict

error_check_for_distributions_and_sample_size()

Check that both an uncertainty distribution exists and sample size has been specified, not one or the other.

Raises:

ValueError – If only one of sample size or uncertainty distribution is provided.

error_check_for_distributions_if_sample_size()

Check that sample sizes align with uncertainty variable definitions.

Raises:

ValueError – If sample sizes are provided without corresponding distributions.

error_check_for_variable_unique_variable_names()

Check that each variable name is unique across all categories.

Raises:

ValueError – If a variable is assigned to multiple uncertainty types or both uncertain and deterministic.

generate_lhs_samples(number_of_variables: int, number_of_samples: int, optimization_method='random-cd')

Generate Latin hypercube samples (LHS) using Scipy’s Quasi-Monte Carlo submodule.

Parameters:

  • number_of_variables (int) – Number of input dimensions.

  • number_of_samples (int) – Number of LHS points to generate.

  • optimization_method (str, optional) – Optimization method for LHS sampling. Defaults to ‘random-cd’.

Returns:

Array of LHS samples of shape (number_of_samples, number_of_variables).

Return type:

np.ndarray

get_parameter_names()

Get all parameter names (deterministic and probabilistic).

Returns:

All variable names included in the study.

Return type:

list of str

get_total_double_loop_sample_size()

Get sample size for double loop style uncertainty study.

Returns:

Product of aleatory and epistemic sample counts.

Return type:

int

get_uncertain_parameter_names()

Get names of all uncertain parameters.

Returns:

Names of aleatory and epistemic variables.

Return type:

list of str

relevant_error_checks()

Perform error checks on specified study details.

uncertainty_definitions docu

class probabilistic.capabilities.uncertainty_definitions.BetaDistribution(name: str, uncertainty_type: str, nominal_value: float, a: float, b: float, loc: float | None = None, scale: float | None = None)

Beta distribution-based uncertainty characterization.

name
Type:

str

uncertainty_type
Type:

str

nominal_value
Type:

float

distribution
Type:

scipy.stats._distn_infrastructure.rv_frozen

a
Type:

float

b
Type:

float

loc
Type:

float

scale
Type:

float

class probabilistic.capabilities.uncertainty_definitions.DeterministicCharacterization(name: str, value: float)

Representation of a deterministic parameter.

name

The name of the parameter.

Type:

str

value

The deterministic value of the parameter.

Type:

float

nominal

The same as value, used for compatibility with uncertain parameter interface.

Type:

float

generate_samples(sample_size)

Generate repeated deterministic samples.

Parameters:

sample_size (int) – Number of samples to generate.

Returns:

Array filled with the same deterministic value.

Return type:

np.ndarray

plot_distribution(alternative_name=False)

Create plot of uncertainty distribution.

Parameters:

alternative_name (str or bool, optional) – Alternative label for the plot. If False (default), uses self.name.

class probabilistic.capabilities.uncertainty_definitions.LognormalDistribution(name: str, uncertainty_type: str, nominal_value: float, mu: float, sigma: float)

Log-Normal Distribution Uncertainty Class

name
Type:

str

uncertainty_type
Type:

str

nominal_value
Type:

float

distribution
Type:

scipy.stats._distn_infrastructure.rv_frozen

's'
Type:

float

'scale'
Type:

float

class probabilistic.capabilities.uncertainty_definitions.NormalDistribution(name: str, uncertainty_type: str, nominal_value: float, mean: float, std_deviation: float)

Normal distribution-based uncertainty characterization.

name
Type:

str

uncertainty_type
Type:

str

nominal
Type:

float

distribution
Type:

scipy.stats._distn_infrastructure.rv_frozen

'loc'
Type:

float

'scale'
Type:

float

class probabilistic.capabilities.uncertainty_definitions.TimeSeriesCharacterization(name: str, value: ndarray)

Representation of a deterministic time-series parameter.

name

The name of the parameter.

Type:

str

value

The deterministic time series values.

Type:

np.ndarray

nominal

Same as value, used for compatibility.

Type:

np.ndarray

generate_samples(sample_size)

Generate copies of the time series.

Parameters:

sample_size (int) – The number of samples to generate.

Returns:

Array of time series values repeated to match the sample size.

Return type:

np.array

plot_distribution(alternative_name=False)

Create plot of uncertainty distribution.

Parameters:

alternative_name (str, optional) – Alternative name to use for the plot. Defaults to False.

class probabilistic.capabilities.uncertainty_definitions.TruncatedLognormalDistribution(name: str, uncertainty_type: str, nominal_value: float, mu: float, sigma: float, lower_bound: float, upper_bound: float)

Truncated Lognormal Distribution Uncertainty Class

name
Type:

str

uncertainty_type
Type:

str

nominal_value
Type:

float

distribution
Type:

scipy.stats._distn_infrastructure.rv_frozen

'loc'
Type:

float

'scale'
Type:

float

'a'
Type:

float

'b'
Type:

float

lower_bound
Type:

float

upper_bound
Type:

float

generate_samples(sample_size: int, random_state=np.random.default_rng())

Generate samples from a truncated lognormal distribution.

Parameters:

  • sample_size (int) – Number of samples to generate.

  • random_state (Generator, optional) – NumPy random number generator instance. If not provided, uses default_rng().

Returns:

Samples drawn from the truncated lognormal distribution.

Return type:

np.ndarray

plot_distribution(alternative_name=False, plot_limits=False)

Plot the probability density function (PDF) of the truncated lognormal distribution.

Parameters:

  • alternative_name (str or bool, optional) – Alternative label for the plot. If False (default), uses the parameter name.

  • plot_limits (tuple of float or bool, optional) – Tuple (min, max) specifying x-axis limits for the plot. If False, defaults to 90%–110% of the lower and upper bounds.

ppf(locations)

Compute the percentile point function (inverse CDF) values in real space.

Parameters:

locations (array_like) – Probabilities at which to evaluate the inverse CDF.

Returns:

Quantile values in real (lognormal) space.

Return type:

np.ndarray

class probabilistic.capabilities.uncertainty_definitions.TruncatedNormalDistribution(name: str, uncertainty_type: str, nominal_value: float, mean: float, std_deviation: float, lower_bound: float, upper_bound: float)

Truncated normal distribution-based uncertainty characterization.

name
Type:

str

uncertainty_type
Type:

str

nominal_value
Type:

float

distribution
Type:

scipy.stats._distn_infrastructure.rv_frozen

'loc'
Type:

float

'scale'
Type:

float

'a'
Type:

float

'b'
Type:

float

class probabilistic.capabilities.uncertainty_definitions.UncertaintyCharacterization(name: str, uncertainty_type: str, nominal_value: float, distribution: str, parameters: dict)

Generic class for uncertain (probabilistic) parameters.

name

Name of the parameter.

Type:

str

uncertainty_type

Type of uncertainty.

Type:

str

nominal

Nominal value.

Type:

float

distribution

The actual scipy.stats distribution object.

Type:

object

parameters

Parameters used to initialize the distribution.

Type:

dict

generate_samples(sample_size: int, random_state=np.random.default_rng())

Generate samples from the uncertainty distribution.

Parameters:

  • sample_size (int) – Number of samples to draw.

  • random_state (Generator, optional) – NumPy random number generator. If not specified, uses default_rng().

Returns:

Array of generated samples.

Return type:

np.ndarray

plot_distribution(alternative_name=False, plot_limits=False)

Plot the probability density function of the distribution.

Parameters:

  • alternative_name (str or bool, optional) – Alternative name to use in the plot label. Defaults to self.name.

  • plot_limits (bool, optional) – Whether to include bounds/limits in the plot. Defaults to False.

ppf(locations)

Compute the Percent Point Function (inverse CDF) at given probabilities.

Parameters:

locations (array_like) – Probabilities at which to evaluate the inverse CDF.

Returns:

Quantiles corresponding to the input probabilities.

Return type:

np.ndarray

class probabilistic.capabilities.uncertainty_definitions.UniformDistribution(name: str, uncertainty_type: str, nominal_value: float, lower_bound: float, upper_bound: float)

Uniform Distribution Uncertainty Class

name
Type:

str

uncertainty_type
Type:

str

nominal_value
Type:

float

distribution
Type:

scipy.stats._distn_infrastructure.rv_frozen

'loc'
Type:

float

'scale'
Type:

float

probabilistic.capabilities.uncertainty_definitions.specify_distribution(parameter_specification)

Generate a distribution object based on a parameter specification.

Parameters:

parameter_specification (dict) –

Dictionary containing the specification of the desired uncertainty distribution. Required keys vary depending on the distribution_type and may include:

  • ’distribution_type’: str, type of distribution (e.g., ‘normal’, ‘beta’)

  • ’uncertainty_type’: str, type of uncertainty

  • ’nominal_value’: float

  • Other distribution-specific parameters (e.g., ‘mean’, ‘std_deviation’, ‘a’, ‘b’)

Returns:

A distribution object based on the specification.

Return type:

UncertaintyCharacterization or DeterministicCharacterization

Raises:

ValueError – If an unsupported distribution type is specified.