uncertaintylib.uncertainty_functions

MIT License

Copyright (c) 2025 Equinor

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Functions

calculate_monte_carlo_statistics(dataframe)

Calculates descriptive statistics on a given pandas DataFrame using Monte Carlo simulation.

calculate_percentage_deviation_from_mean(...)

Calculates the percentage deviation from mean of each column in a given pandas DataFrame.

calculate_sensitivity_coefficients(indata, ...)

Calculate the absolute and relative sensitivity coefficients for input parameters to a given function.

calculate_uncertainty(indata, function)

Analyze the uncertainty of output parameters for a given function and input data.

combined_standard_uncertainty(u_xi[, ci])

Calculates the combined standard uncertainty from a dictionary of input uncertainties u_xi and a dictionary of sensitivity coefficients ci.

compare_monte_carlo_to_conventional_uncertainty_calculation(...)

filter_uncertainty_results(...)

Filter uncertainty (from calculate_uncertainty) results by a specific tag.

generate_normal_distribution(mean, stddev, N)

Generates a random sample from a truncated normal distribution using rejection sampling.

monte_carlo_output_correlations(outputs[, ...])

Calculate the Pearson correlation coefficients between each pair of outputs.

monte_carlo_simulation(mc_input, function, n)

Runs a Monte Carlo simulation for the given input arguments and the provided function and returns the evaluation of the function with Monte Carlo data as a pandas DataFrame.

standard_uncertainty_selector(indata)

Selects either standard uncertainty or percentage-based standard uncertainty for each input parameter in a given dictionary, and returns the largest of the two.

uncertaintylib.uncertainty_functions.calculate_uncertainty(indata, function)[source]

Analyze the uncertainty of output parameters for a given function and input data. The method used is the method described as “Determining combined standard uncertainty” for “Uncorrelated input quantities” given in chapter 5 in “JCGM 100:2008 Evaluation of measurement data — Guide to the expression of uncertainty in measurement” The equation in use is equation (10) in chapter 5.1.2.

Handling of standard uncertainty:

Both ‘standard_uncertainty’ and ‘standard_uncertainty_percent’ can be given. If only one is given, it will use that one. However, If both are given, the code will use the largest of the two (in absolute values).

Parameters:
  • indata (dict) –

    A dictionary that holds the following required keys:
    ’mean’dict

    A dictionary that holds the mean values for each input parameter.

    ’standard_uncertainty’dict

    A dictionary that holds the standard uncertainty values for each input parameter.

    ’standard_uncertainty_percent’: dict

    A dictionary that holds the percentage standard uncertainty for each input parameter.

  • function (callable) – A function that takes an input dictionary and returns a dictionary of output parameters.

Returns:

dict –

A dictionary with the following keys and values:
’varians’dict

A dictionary of nested dictionaries that holds the varians for each input parameter for each output parameter.

’contribution’dict

A dictionary of nested dictionaries that contains the percentage contribution of each input variable to the uncertainty in each output variable.

’u’dict

A dictionary of the Combined Standard Uncertainty (u) for each output parameter.

’U’dict

A dictionary of the Expanded Uncertainty (95% confidence level)(U,k=2) for each output parameter.

’U_perc’dict

A dictionary of the Relative Expanded Uncertainty (95% confidence level)(U, k=2) for each output parameter, in %.

Return type:

dict

uncertaintylib.uncertainty_functions.calculate_sensitivity_coefficients(indata, function)[source]

Calculate the absolute and relative sensitivity coefficients for input parameters to a given function.

If an input parameter is set to distribution = ‘none’, the sensitivity coefficients will be 0 for this variable. This will for example be the case for settings used as input to the function, where values can be 0,1,2 etc.

Parameters:
  • indata (dict) –

    A dictionary containing the input parameters, standard uncertainties, distribution, minimum and maximum values. The dictionary must have the following keys:

    • ’mean’ : dict A dictionary that holds the mean values for each input parameter.

    • ’standard_uncertainty’ : dict A dictionary that holds the standard uncertainty values for each input parameter.

    • ’standard_uncertainty_percent’: dict A dictionary that holds the percentage standard uncertainty for each input parameter.

    • ’distribution’ : dict, optional A dictionary that holds the distribution used for each parameter. Default is ‘normal’

    • ’min’: dict, optional A dictionary that holds the minimum values for each input parameter. Not specified if missing.

    • ’max’: dict, optional A dictionary that holds the maximum values for each input parameter. Not specified if missing.

  • function (callable) – A function that takes an input dictionary and returns a dictionary of output parameters.

Returns:

dict – A dictionary containing three keys:

  • ’absolute_sensitivity_coefficients’: dict A dictionary of absolute sensitivity coefficients for each input parameter (key) with respect to each output parameter (sub-key).

  • ’relative_sensitivity_coefficients’: dict A dictionary of relative sensitivity coefficients (percentage change in output / percentage change in input) for each input parameter (key) with respect to each output parameter (sub-key).

  • ’baseline_results’: dict A dictionary of output values for the original inputs (given by the ‘mean’ input dictionary)

Return type:

dict

uncertaintylib.uncertainty_functions.monte_carlo_simulation(mc_input, function, n)[source]

Runs a Monte Carlo simulation for the given input arguments and the provided function and returns the evaluation of the function with Monte Carlo data as a pandas DataFrame.

Handling of standard uncertainty:

The input standard uncertainty is used as standard deviation when generating distributions of the input parameters used in the monte carlo. Both ‘standard_uncertainty’ and ‘standard_uncertainty_percent’ can be given. If only one is given, it will use that one. However, If both are given, the code will use the largest of the two (in absolute values).

Parameters:
  • mc_input (dict) –

    A nested dictionary containing the following sub-dictionaries:
    ’mean’dict

    A dictionary with input parameter names as keys and mean values as values.

    ’standard_uncertainty’dict

    A dictionary with input parameter names as keys and standard uncertainty values as values.

    ’standard_uncertainty_percent’dict

    A dictionary with input parameter names as keys and percentages of the standard uncertainty as values.

    ’distribution’dict, optional
    A dictionary with input parameter names as keys and distribution types (‘normal’, ‘uniform’, or ‘none’) as values. Default is ‘normal’.
    • ’normal’: Generates random samples using a normal distribution with input parameter mean and standard uncertainty value.

    • ’uniform’: Generates random samples using a uniform distribution with input parameter minimum and maximum values.

    • ’none’: Generates a fixed value with input parameter mean.

    ’min’dict, optional

    A dictionary with input parameter names as keys and minimum values for each parameter as values, in the same unit as ‘mean’. A value of None or nan means no minimum limit. If not present in ‘mc_input’, the distribution will not be truncated at a minimum value.

    ’max’dict, optional

    A dictionary with input parameter names as keys and maximum values for each parameter as values, in the same unit as ‘mean’. A value of None or nan means no maximum limit. If not present in ‘mc_input’, the distribution will not be truncated at a maximum value.

  • function (callable) – The function to be evaluated

  • n (int) – The number of Monte Carlo perturbations to run

Returns:

pd.DataFrame – A DataFrame of the function evaluations with Monte Carlo data generated from the provided parameters

Return type:

DataFrame

uncertaintylib.uncertainty_functions.combined_standard_uncertainty(u_xi, ci=None)[source]

Calculates the combined standard uncertainty from a dictionary of input uncertainties u_xi and a dictionary of sensitivity coefficients ci. Both the uncertainties and the sensitivity coefficients can be given either as relative (%) values or absolute values. If relative values are given, the result will also be a relative uncertainty, while if absolute values are used, the uncertainty will also be absolute. The function assumes that all input uncertainties and sensitivity coefficients are given as single standard uncertainties (k=1).

If sensitivity coefficients are not given, sensitivity coefficients of 1 will be used.

Parameters:
  • u_xi (dict) – Dictionary of input uncertainties, with keys corresponding to variable names and values corresponding to the uncertainty values.

  • ci (dict, optional) – Dictionary of sensitivity coefficients, with keys corresponding to variable names and values corresponding to the sensitivity coefficient values. Default is None, in which case a sensitivity value of 1.0 is assumed for all input variables.

Returns:

float – The combined standard uncertainty, calculated as the square root of the sum of the squares of the product of each input uncertainty with its corresponding sensitivity coefficient.

Return type:

float

uncertaintylib.uncertainty_functions.generate_normal_distribution(mean, stddev, N, lower_boundary=-inf, upper_boundary=inf, iteration_limit=1000)[source]

Generates a random sample from a truncated normal distribution using rejection sampling. I.e. values outside the boundaries will be resampled.

Parameters:
  • mean (float) – Mean of the normal distribution.

  • stddev (float) – standard deviation of the normal distribution.

  • N (int) – Number of random samples to generate.

  • lower_boundary (float, optional) – Lower boundary for the truncated distribution (default is -inf).

  • upper_boundary (float, optional) – Upper boundary for the truncated distribution (default is inf).

  • iteration_limit (int, optional) – Maximum number of iterations allowed for rejection sampling (default is 1000).

Returns:

samples (numpy.ndarray) – Array of size N containing the truncated normal distribution.

Raises:

ValueError – If lower_boundary is greater than upper_boundary.

Return type:

ndarray

Notes

This function generates a random sample of size N from a normal distribution with mean and standard deviation specified by mean and stddev, respectively, and removes samples that are outside of the lower and upper boundaries specified by lower_boundary and upper_boundary, respectively. Samples that fall outside of these boundaries are removed using rejection sampling. If the total number of samples generated is less than N, the function will continue to generate additional samples using rejection sampling until N samples have been generated or until the maximum number of iterations (specified by iteration_limit) has been reached.

uncertaintylib.uncertainty_functions.standard_uncertainty_selector(indata)[source]

Selects either standard uncertainty or percentage-based standard uncertainty for each input parameter in a given dictionary, and returns the largest of the two.

The reason for utilizing a max selector, is because many measurement principle have uncertainties that are given as a percentage in certain ranges while in lower ranges the uncertainty is dominated by other factors (such as noise), which is better represented by an absolute uncertainty value

Parameters:

indata (dict) –

A dictionary that holds the following required keys:

’mean’dict

A dictionary that holds the mean values for each input parameter.

’standard_uncertainty’dict

A dictionary that holds the standard uncertainty values for each input parameter.

’standard_uncertainty_percent’dict, optional

A dictionary that holds the percentage standard uncertainty for each input parameter.

Returns:

dict – A dictionary that holds the standard uncertainty used for each input parameter, either from the ‘standard_uncertainty’ column or calculated from the ‘standard_uncertainty_percent’ column, whichever is larger. This is the standard uncertainty in absolute value (same unit as the mean), not the percentage standard uncertainty. This standard uncertainty is the one being used in uncertainty calculations (such as monte carlo or traditional uncertainty calculation)

Return type:

dict

Notes

If the ‘standard_uncertainty_percent’ key is not present in the input dictionary, the function returns the ‘standard_uncertainty’ key.

uncertaintylib.uncertainty_functions.calculate_percentage_deviation_from_mean(dataframe)[source]

Calculates the percentage deviation from mean of each column in a given pandas DataFrame.

Parameters:

dataframe (pandas DataFrame) – The DataFrame to calculate the percentage deviation.

Returns:

pandas DataFrame – A DataFrame where each column contains the percentage deviation from mean of the respective column in the input DataFrame. The percentage deviation of each element in a column is calculated as the difference between the value of each element and the mean value of that column, divided by the mean value of that column, and then multiplied by 100. This calculation is commonly used in statistical analysis to understand how much each data point in a column varies from the mean of that column.

Return type:

DataFrame

uncertaintylib.uncertainty_functions.calculate_monte_carlo_statistics(dataframe)[source]

Calculates descriptive statistics on a given pandas DataFrame using Monte Carlo simulation.

Parameters:

dataframe (pandas DataFrame) – The DataFrame for which to calculate the Monte Carlo statistics. Each column of the DataFrame should contain a result vector from a Monte Carlo simulation.

Returns:

pandas DataFrame – A DataFrame containing the mean, standard deviation (std_dev), standard deviation as a percentage of the mean (std_dev_percent), two times the standard deviation (std_dev_k2), and two times the standard deviation as a percentage of the mean (std_dev_percent_k2) for each column of the original DataFrame. If the mean of a column is zero, the standard deviation as a percentage and two times the standard deviation as a percentage are set to NaN because they are not defined.

Return type:

DataFrame

uncertaintylib.uncertainty_functions.monte_carlo_output_correlations(outputs, return_as_dataframe=False)[source]

Calculate the Pearson correlation coefficients between each pair of outputs.

Parameters:

outputspandas DataFrame

A DataFrame containing the output variables.

return_as_dataframeboolean, default False

If True, return the results as a DataFrame. If False, return the results as a dictionary.

Returns:

If return_as_dataframe is True:
correlationspandas DataFrame

A DataFrame containing the pairwise correlation coefficients between the output variables.

If return_as_dataframe is False:
resultsdictionary

A dictionary containing the pairwise correlation coefficients between the output variables. The keys are in the format “output1 and output2”.

Parameters:
  • outputs (DataFrame)

  • return_as_dataframe (bool)

Return type:

Any

uncertaintylib.uncertainty_functions.filter_uncertainty_results(tag_filter_string, uncertainty_results)[source]

Filter uncertainty (from calculate_uncertainty) results by a specific tag. This is useful when calculate_uncertainty is applied for functions returning thousands of outputs

Parameters:

tag_filter_stringstr

A string used to filter the uncertainty results based on the key.

uncertainty_resultsdict

A nested dictionary containing uncertainty results for different parameters.

Returns:

filtered_results: dict

A nested dictionary containing filtered uncertainty results based on the tag filter string.

Parameters:
  • tag_filter_string (str)

  • uncertainty_results (dict)

Return type:

dict

uncertaintylib.uncertainty_functions.compare_monte_carlo_to_conventional_uncertainty_calculation(MC_results, uncertainty_results)[source]
Parameters:
  • MC_results (pandas DataFrame) – Dataframe containing results from Monte Carlo simulation (returned by monte_carlo_simulation function)

  • uncertainty_results (dict) – Dictionary containing all results from traditional uncertainty calculations (returned by calculate_uncertainty function)

Returns:

df (pandas DataFrame) – Dataframe containing comparison between relative uncertainty (k=2) from conventional uncertainty calculations and monte carlo.

Return type:

DataFrame