Represents a parametric probability distribution for uncertainty quantification. More...

#include <cmbdistribution.h>

Collaboration diagram for Distribution:

Public Member Functions
	Distribution ()
	Default constructor.

	Distribution (const Distribution &dist)
	Copy constructor.

Distribution &	operator= (const Distribution &dist)
	Assignment operator.

double	Eval (const double &x) const
	Evaluate probability density function at a given value.

double	EvalLog (const double &x)
	Evaluate natural logarithm of probability density.

TimeSeries< double >	EvaluateAsTimeSeries (int numberofpoint=100, const double &stdcoeff=4)
	Generate time series representation of the distribution for plotting.

void	SetType (const distribution_type &typ)
	Set the distribution type and resize parameters vector.

double	Mean (parameter_mode param_mode=parameter_mode::based_on_fitted_distribution)
	Calculate the mean (expected value) of the distribution.

void	SetDataMean (const double &val)
	Set the empirical mean from original data.

void	SetDataSTDev (const double &val)
	Set the empirical standard deviation from original data.

double	DataMean ()
	Get the stored empirical mean.

double	DataSTDev ()
	Get the stored empirical standard deviation.

bool	operator== (const string &dist_type)
	Compare distribution type with a string identifier.

Static Public Member Functions
static double	Eval (const double &x, const vector< double > parameters, distribution_type distribution)
	Static method to evaluate PDF with explicit parameters.

static TimeSeries< double >	EvaluateAsTimeSeries (int numberofpoints, const double &stdcoeff, const vector< double > parameters, distribution_type &dist_type)
	Static method to generate time series with explicit parameters.

Public Attributes
vector< double >	parameters
	Distribution parameters vector.

distribution_type	distribution = distribution_type::none
	The type of probability distribution.

Private Attributes
double	mean_val = 0
	Empirical mean from original sample data.

double	std_val = 0
	Empirical standard deviation from original sample data.

Static Private Attributes
static double	pi = 4 * atan(1.0)
	Mathematical constant π (pi)

Detailed Description

Represents a parametric probability distribution for uncertainty quantification.

The Distribution class provides:

Probability density evaluation (PDF)
Log-probability evaluation (for numerical stability in Bayesian inference)
Distribution visualization
Parameter storage for various distribution types
Conversion between data statistics and distribution parameters

Supported Distributions

Normal Distribution

Parameters: [μ, σ] where μ is mean, σ is standard deviation
PDF: p(x) = (1/(√(2π)σ)) × exp(-(x-μ)²/(2σ²))
Support: (-∞, +∞)
Use case: Tracer concentrations with symmetric uncertainty, isotopic ratios

Lognormal Distribution

Parameters: [μ_log, σ_log] in log-space
PDF: p(x) = (1/(x√(2π)σ_log)) × exp(-(ln(x)-μ_log)²/(2σ_log²))
Support: (0, +∞)
Use case: Elemental concentrations (strictly positive), ratios
Mean: exp(μ_log + σ_log²/2)

Uniform/Dirichlet Distribution

Parameters: None (implicitly [0,1])
PDF: p(x) = 1 for x ∈ [0,1], else very small (1e-32)
Support: [0, 1]
Use case: Non-informative priors for source contributions

Usage in SedSat3

This class is central to:

Prior distributions (Parameter class) for Bayesian inference
Measurement uncertainty (ConcentrationSet) for error propagation
Fitted distributions for tracer selection (normality tests)

Note: Thread-safe for const operations after initialization

See also: Parameter; ConcentrationSet

Example usage:

// Create a normal distribution for a tracer concentration
Distribution tracerDist;
tracerDist.SetType(distribution_type::normal);
tracerDist.parameters = {50.0, 5.0};  // μ=50 mg/kg, σ=5 mg/kg
 
// Evaluate probability density
double pdf = tracerDist.Eval(55.0);
 
// Evaluate log-probability (preferred for Bayesian calculations)
double logPdf = tracerDist.EvalLog(55.0);
 
// Generate visualization data
TimeSeries<double> curve = tracerDist.EvaluateAsTimeSeries(200, 3.0);

Definition at line 95 of file cmbdistribution.h.

Constructor & Destructor Documentation

◆ Distribution() [1/2]

Distribution::Distribution ( )

Default constructor.

Initializes a Distribution with:

distribution = distribution_type::none
Empty parameters vector
Zero mean and standard deviation

Postcondition: pi is initialized to π (3.14159...)

Definition at line 6 of file cmbdistribution.cpp.

◆ Distribution() [2/2]

Distribution::Distribution ( const Distribution & dist )

Copy constructor.

Parameters

dist	The Distribution object to copy from

Creates a deep copy including:

Distribution type
All parameters
Empirical statistics (mean_val, std_val)

Definition at line 90 of file cmbdistribution.cpp.

References distribution, mean_val, parameters, pi, SetType(), and std_val.

Member Function Documentation

◆ DataMean()

double Distribution::DataMean ( )

inline

Get the stored empirical mean.

Returns: The empirical mean from original data

Definition at line 336 of file cmbdistribution.h.

References mean_val.

Referenced by SourceSinkData::BuildSourceMeanMatrix(), and SourceSinkData::BuildSourceMeanMatrix_Isotopes().

◆ DataSTDev()

double Distribution::DataSTDev ( )

inline

Get the stored empirical standard deviation.

Returns: The empirical standard deviation from original data

Definition at line 344 of file cmbdistribution.h.

References std_val.

◆ Eval() [1/2]

double Distribution::Eval ( const double & x ) const

Evaluate probability density function at a given value.

Parameters

x	The value at which to evaluate the PDF

Returns: The probability density p(x)

Computes the probability density function value. For continuous distributions, this is NOT a probability (which would require integration), but the density at point x.

Mathematical Formulas:

Normal: p(x) = (1/(√(2π)σ)) × exp(-(x-μ)²/(2σ²))

Lognormal: p(x) = (1/(x√(2π)σ_log)) × exp(-(ln(x)-μ_log)²/(2σ_log²))

Uniform/Dirichlet: p(x) = 1 for x ∈ [0,1], else 1×10⁻³²

Note: For numerical reasons, uniform distributions return 1e-32 (not exactly 0) outside [0,1]; Prefer EvalLog() for Bayesian calculations to avoid underflow

See also: EvalLog()

Definition at line 11 of file cmbdistribution.cpp.

References dirichlet, distribution, log, lognormal, normal, parameters, pi, uniform, and x.

Referenced by ConcentrationSet::CalculateLogLikelihood(), ConcentrationSet::CreateFittedDistribution(), EvaluateAsTimeSeries(), and EvaluateAsTimeSeries().

◆ Eval() [2/2]

double Distribution::Eval	(	const double &	x,
		const vector< double >	parameters,
		distribution_type	distribution
	)

static

Static method to evaluate PDF with explicit parameters.

Parameters

x	The value at which to evaluate
parameters	Distribution parameters [μ, σ] or [μ_log, σ_log]
distribution	The distribution type

Returns: The probability density p(x)

Utility function for evaluating PDFs without creating a Distribution object. Useful for one-off calculations or testing.

Example:

vector<double> params = {0.0, 1.0};  // Standard normal
double pdf = Distribution::Eval(1.96, params, distribution_type::normal);
// pdf ≈ 0.0584 (height of N(0,1) at 1.96σ)

Definition at line 24 of file cmbdistribution.cpp.

References dirichlet, distribution, log, lognormal, normal, parameters, pi, uniform, and x.

◆ EvalLog()

double Distribution::EvalLog ( const double & x )

Evaluate natural logarithm of probability density.

Parameters

x	The value at which to evaluate

Returns: ln(p(x)) - natural log of probability density

Computes the log-probability density, which is numerically more stable than Eval() for Bayesian inference. This prevents underflow when multiplying many small probabilities and is faster (avoids division and some exponentials).

Mathematical Formulas:

Normal: ln(p(x)) = -ln(√(2π)σ) - (x-μ)²/(2σ²)

Lognormal: ln(p(x)) = -ln(√(2π)σ_log×x) - (ln(x)-μ_log)²/(2σ_log²)

Uniform/Dirichlet: ln(p(x)) = 0 for x ∈ [0,1], else -1×10⁶ (effectively -∞)

Usage in Bayesian Inference:

Log-posterior = log-likelihood + log-prior:

double logPosterior = logLikelihood + prior.EvalLog(theta);

Note: Returns large negative value (-1e6) instead of -∞ for numerical stability; This is the preferred method for MCMC and optimization

See also: CalcLogPriorProbability()

Definition at line 37 of file cmbdistribution.cpp.

References dirichlet, distribution, log, lognormal, normal, parameters, pi, uniform, and x.

Referenced by Parameter::CalcLogPriorProbability(), and SourceSinkData::LogLikelihoodSourceElementalDistributions().

◆ EvaluateAsTimeSeries() [1/2]

TimeSeries< double > Distribution::EvaluateAsTimeSeries	(	int	numberofpoint = `100`,
		const double &	stdcoeff = `4`
	)

Generate time series representation of the distribution for plotting.

Parameters

numberofpoint	Number of points to generate (default: 100)
stdcoeff	Number of standard deviations to span (default: 4, i.e., ±4σ)

Returns: TimeSeries containing (x, p(x)) pairs for visualization

Creates a discrete representation of the PDF suitable for plotting in GUI. The x-values span from (μ - stdcoeff×σ) to (μ + stdcoeff×σ) for normal distributions, or the equivalent in log-space for lognormal distributions.

Coverage by stdcoeff:

stdcoeff = 1: ~68% of probability mass (±1σ)
stdcoeff = 2: ~95% of probability mass (±2σ)
stdcoeff = 3: ~99.7% of probability mass (±3σ)
stdcoeff = 4: ~99.99% of probability mass (±4σ, default)

Note: For lognormal, x values are exp(μ_log ± stdcoeff×σ_log); The returned TimeSeries can be directly plotted or exported

Example:

Distribution dist;
dist.SetType(distribution_type::normal);
dist.parameters = {100.0, 10.0};
 
// Generate curve spanning ±3σ (99.7% of mass)
TimeSeries<double> curve = dist.EvaluateAsTimeSeries(200, 3.0);
// curve contains 200 points from x=70 to x=130

Definition at line 51 of file cmbdistribution.cpp.

References distribution, Eval(), lognormal, normal, parameters, and x.

Referenced by MainWindow::showdistributionsforelements().

◆ EvaluateAsTimeSeries() [2/2]

TimeSeries< double > Distribution::EvaluateAsTimeSeries	(	int	numberofpoints,
		const double &	stdcoeff,
		const vector< double >	parameters,
		distribution_type &	dist_type
	)

static

Static method to generate time series with explicit parameters.

Parameters

numberofpoints	Number of points to generate
stdcoeff	Number of standard deviations to span
parameters	Distribution parameters [μ, σ] or [μ_log, σ_log]
dist_type	The distribution type

Returns: TimeSeries containing (x, p(x)) pairs

Static version of EvaluateAsTimeSeries() for generating curves without creating a Distribution object.

See also: EvaluateAsTimeSeries(int, const double&)

Definition at line 70 of file cmbdistribution.cpp.

References Eval(), lognormal, normal, parameters, and x.

◆ Mean()

double Distribution::Mean ( parameter_mode param_mode = parameter_mode::based_on_fitted_distribution )

Calculate the mean (expected value) of the distribution.

Parameters

param_mode Whether to use empirical data or distribution parameters

Returns: The mean value E[X]

Computes the expected value based on the selected mode:

direct mode: Returns the stored empirical mean (mean_val) from original data

based_on_fitted_distribution mode (default):

Normal: μ (parameters[0])
Lognormal: exp(μ_log + σ_log²/2) (accounting for log-space variance)
Others: 0

Note: For lognormal, the mean in real space is NOT simply exp(μ_log)

See also: SetDataMean()

Definition at line 120 of file cmbdistribution.cpp.

References direct, distribution, lognormal, mean_val, normal, and parameters.

Referenced by SourceSinkData::BuildSourceMeanMatrix(), and SourceSinkData::BuildSourceMeanMatrix_Isotopes().

◆ operator=()

Distribution & Distribution::operator= ( const Distribution & dist )

Assignment operator.

Parameters

dist	The Distribution object to copy from

Returns: Reference to this object for chaining

Copies all distribution data and reinitializes pi constant.

Definition at line 99 of file cmbdistribution.cpp.

References distribution, mean_val, parameters, pi, SetType(), and std_val.

◆ operator==()

bool Distribution::operator== ( const string & dist_type )

Compare distribution type with a string identifier.

Parameters

dist_type String name of distribution ("normal", "log-normal", "uniform", "dirichlet")

Returns: true if distribution matches the string type

Convenience method for string-based type checking, useful for configuration file parsing or user input validation.

Recognized strings:

"normal" → distribution_type::normal
"log-normal" → distribution_type::lognormal
"uniform" → distribution_type::uniform or dirichlet
"dirichlet" → distribution_type::dirichlet

Example:

if (dist == "normal") {
    // Handle normal distribution case
}

Definition at line 133 of file cmbdistribution.cpp.

References dirichlet, distribution, lognormal, normal, and uniform.

◆ SetDataMean()

void Distribution::SetDataMean ( const double & val )

inline

Set the empirical mean from original data.

Parameters

val	The empirical mean value

Stores the sample mean calculated directly from observed data, independent of the fitted distribution parameters.

Definition at line 317 of file cmbdistribution.h.

References mean_val.

Referenced by ConcentrationSet::EstimateDistributionParameters().

◆ SetDataSTDev()

void Distribution::SetDataSTDev ( const double & val )

inline

Set the empirical standard deviation from original data.

Parameters

val	The empirical standard deviation

Stores the sample standard deviation calculated directly from observed data, independent of the fitted distribution parameters.

Definition at line 328 of file cmbdistribution.h.

References std_val.

Referenced by ConcentrationSet::EstimateDistributionParameters().

◆ SetType()

void Distribution::SetType ( const distribution_type & typ )

Set the distribution type and resize parameters vector.

Parameters

typ	The distribution type to set

Sets the distribution type and automatically resizes the parameters vector:

Normal → 2 parameters [μ, σ]
Lognormal → 2 parameters [μ_log, σ_log]
Others → no automatic resize

Postcondition: parameters vector is appropriately sized

Note: Does not initialize parameter values, only sizes the vector

Definition at line 110 of file cmbdistribution.cpp.

References distribution, lognormal, normal, and parameters.

Referenced by Distribution(), ConcentrationSet::EstimateDistributionParameters(), and operator=().

Member Data Documentation

◆ distribution

distribution_type Distribution::distribution = distribution_type::none

The type of probability distribution.

Determines which PDF formula to use in Eval() and EvalLog(). Default is distribution_type::none (uninitialized).

Definition at line 275 of file cmbdistribution.h.

Referenced by Distribution(), SourceSinkData::AssignAllDistributions(), ConcentrationSet::CalculateLogLikelihood(), ConcentrationSet::EstimateDistributionParameters(), Eval(), Eval(), EvalLog(), EvaluateAsTimeSeries(), Mean(), operator=(), operator==(), Parameter::SetPriorDistribution(), SetType(), and Parameter::UpdatePriorDistribution().

◆ mean_val

double Distribution::mean_val = 0

private

Empirical mean from original sample data.

Stores the sample mean calculated directly from observed tracer concentrations or other measured data. This is independent of any fitted distribution parameters and represents the actual data statistics.

Used when param_mode::direct is specified in Mean().

Definition at line 391 of file cmbdistribution.h.

Referenced by Distribution(), DataMean(), Mean(), operator=(), and SetDataMean().

◆ parameters

vector<double> Distribution::parameters

Distribution parameters vector.

Storage for distribution-specific parameters:

Normal: parameters[0] = μ (mean), parameters[1] = σ (std dev)
Lognormal: parameters[0] = μ_log, parameters[1] = σ_log
Uniform/Dirichlet: Empty or unused

Note: Size is automatically adjusted by SetType(); Direct public access provided for flexibility

Definition at line 267 of file cmbdistribution.h.

Referenced by Distribution(), SourceSinkData::AssignAllDistributions(), ConcentrationSet::CalculateLogLikelihood(), ConcentrationSet::EstimateDistributionParameters(), Eval(), Eval(), EvalLog(), EvaluateAsTimeSeries(), EvaluateAsTimeSeries(), ConcentrationSet::GetEstimatedMu(), ConcentrationSet::GetEstimatedSigma(), SourceSinkData::InitializeParametersAndObservations(), Mean(), operator=(), ConcentrationSet::SetEstimatedMu(), ConcentrationSet::SetEstimatedSigma(), SetType(), and Parameter::UpdatePriorDistribution().

◆ pi

double Distribution::pi = 4 * atan(1.0)

staticprivate

Mathematical constant π (pi)

Computed once as 4×arctan(1) ≈ 3.14159265359 Used in normal and lognormal PDF calculations.

Note: Static member shared across all Distribution instances

Definition at line 380 of file cmbdistribution.h.

Referenced by Distribution(), Eval(), Eval(), EvalLog(), and operator=().

◆ std_val

double Distribution::std_val = 0

private

Empirical standard deviation from original sample data.

Stores the sample standard deviation calculated directly from observations. Represents actual data variability independent of fitted distribution.

Definition at line 399 of file cmbdistribution.h.

Referenced by Distribution(), DataSTDev(), operator=(), and SetDataSTDev().

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Public Attributes

Private Attributes

Static Private Attributes

Detailed Description

Supported Distributions

Normal Distribution

Lognormal Distribution

Uniform/Dirichlet Distribution

Usage in SedSat3

Constructor & Destructor Documentation

◆ Distribution() [1/2]

◆ Distribution() [2/2]

Member Function Documentation

◆ DataMean()

◆ DataSTDev()

◆ Eval() [1/2]

Mathematical Formulas:

◆ Eval() [2/2]

◆ EvalLog()

Mathematical Formulas:

Usage in Bayesian Inference:

◆ EvaluateAsTimeSeries() [1/2]

Coverage by stdcoeff:

◆ EvaluateAsTimeSeries() [2/2]

◆ Mean()

◆ operator=()

◆ operator==()

◆ SetDataMean()

◆ SetDataSTDev()

◆ SetType()

Member Data Documentation

◆ distribution

◆ mean_val

◆ parameters

◆ pi

◆ std_val