Represents a model parameter with prior distribution and constraints. More...

#include <parameter.h>

Collaboration diagram for Parameter:

Public Member Functions
	Parameter ()
	Default constructor.

	Parameter (const Parameter &param)
	Copy constructor.

Parameter &	operator= (const Parameter &param)
	Assignment operator.

void	SetPriorDistribution (distribution_type dist_type)
	Set the type of prior probability distribution.

Distribution &	GetPriorDistribution ()
	Get reference to the prior distribution object.

bool	operator== (const string &dist_type)
	Compare parameter with a string (unused, legacy method)

double	GetVal (const string &quantity)
	Get range bound by string identifier.

void	SetRange (const vector< double > &rng)
	Set the parameter range from a vector.

void	SetRange (double low, double high)
	Set the parameter range from individual bounds.

double	GetRange (_range lowhigh)
	Get a specific range bound.

void	SetRange (_range, double value)
	Set a specific range bound.

void	SetName (const string &nam)
	Set the parameter name/identifier.

string	Name () const
	Get the parameter name.

double	Value () const
	Get the current parameter value.

void	SetValue (double val)
	Set the current parameter value.

double	GetValue ()
	Get the current parameter value (alternative accessor)

void	UpdatePriorDistribution ()
	Update prior distribution parameters based on current range.

double	CalcLogPriorProbability (const double x)
	Calculate log prior probability density at a given value.

Private Attributes
Distribution	prior_distribution
	The prior probability distribution for this parameter.

vector< double >	range
	Allowable range for the parameter [low, high].

string	name
	Parameter name/identifier.

double	value = 0
	Current value of the parameter.

Detailed Description

Represents a model parameter with prior distribution and constraints.

The Parameter class encapsulates a single model parameter used in statistical inference, optimization, and uncertainty quantification. It stores:

Current parameter value
Allowable range (bounds) for optimization and sampling
Prior probability distribution for Bayesian inference
Parameter name/identifier

This class is fundamental to SedSat3's statistical approaches:

Bayesian MCMC: Prior distributions guide Markov Chain sampling
Genetic Algorithms: Ranges define feasible search space
Maximum Likelihood Estimation: Ranges constrain optimization

Parameters typically represent source contributions in sediment fingerprinting, with values constrained between 0 and 1 (or 0-100%), and prior distributions reflecting expert knowledge or constraints from the mixing model.

Prior Distribution Parameterization

The class automatically parameterizes prior distributions based on the specified range using UpdatePriorDistribution():

Normal distribution: Centered at midpoint with std dev = 0.25 × (high - low)
- μ = 0.5 × (low + high)
- σ = 0.25 × (high - low)
Lognormal distribution: Parameters calculated in log-space
- μ_log = 0.5 × (ln(low) + ln(high))
- σ_log = 0.25 × (ln(high) - ln(low))

This automatic parameterization ensures that approximately 95% of the prior probability mass falls within the specified range (assuming ±2σ coverage).

Note: Thread-safe for read-only operations after initialization

Warning: Changing the range automatically updates prior distribution parameters

See also: Distribution; distribution_type

Example usage:

// Create a parameter for agricultural source contribution
Parameter sourceContribution;
sourceContribution.SetName("Agricultural");
sourceContribution.SetRange(0.0, 1.0);  // 0-100% contribution
sourceContribution.SetPriorDistribution(distribution_type::normal);
 
// The prior is automatically N(0.5, 0.25²)
double logProb = sourceContribution.CalcLogPriorProbability(0.3);

Definition at line 72 of file parameter.h.

Constructor & Destructor Documentation

◆ Parameter() [1/2]

Parameter::Parameter ( )

Default constructor.

Initializes a Parameter object with:

Empty name
Value of 0.0
Range vector with 2 elements (uninitialized bounds)
Default prior distribution (uniform)

Postcondition: range vector is sized to 2 elements

Definition at line 3 of file parameter.cpp.

References range.

◆ Parameter() [2/2]

Parameter::Parameter ( const Parameter & param )

Copy constructor.

Parameters

param The Parameter object to copy from

Creates a deep copy of another Parameter, including:

Name
Current value
Range bounds
Complete prior distribution specification

Definition at line 58 of file parameter.cpp.

References name, prior_distribution, and range.

Member Function Documentation

◆ CalcLogPriorProbability()

double Parameter::CalcLogPriorProbability ( const double x )

Calculate log prior probability density at a given value.

Parameters

x	The value at which to evaluate the log prior probability

Returns: Natural logarithm of the prior probability density at x

Evaluates ln(p(x)) where p is the prior probability density function. Used in Bayesian inference to calculate:

Log posterior probability: ln(p(θ|data)) = ln(p(data|θ)) + ln(p(θ))
Metropolis-Hastings acceptance ratios
Maximum a posteriori (MAP) estimates

Using log probabilities prevents numerical underflow and is computationally more stable for MCMC sampling.

Note: Returns -∞ (or very large negative value) if x is outside support of distribution

See also: Distribution::EvalLog()

Example:

Parameter source;
source.SetRange(0.0, 1.0);
source.SetPriorDistribution(distribution_type::normal);
 
double logPrior = source.CalcLogPriorProbability(0.5);  // Highest at mean
double logPrior2 = source.CalcLogPriorProbability(0.95); // Lower at tail

Definition at line 90 of file parameter.cpp.

References Distribution::EvalLog(), prior_distribution, and x.

◆ GetPriorDistribution()

Distribution & Parameter::GetPriorDistribution ( )

inline

Get reference to the prior distribution object.

Returns: Reference to the internal Distribution object

Provides direct access to the prior distribution for:

Querying distribution parameters
Evaluating probability densities
Sampling from the distribution

Warning: Modifying the returned distribution directly may lead to inconsistency with the parameter range

Definition at line 144 of file parameter.h.

References prior_distribution.

◆ GetRange()

double Parameter::GetRange ( _range lowhigh )

Get a specific range bound.

Parameters

lowhigh Specifies which bound to retrieve

Returns: The requested bound value, or 0 if range is not properly initialized

Type-safe method for retrieving range bounds.

Precondition: range vector must be properly initialized (size == 2)

Definition at line 25 of file parameter.cpp.

References low, and range.

◆ GetVal()

double Parameter::GetVal ( const string & quantity )

Get range bound by string identifier.

Parameters

quantity String specifying which bound: "high" or "low"

Returns: The requested range bound, or 0 if quantity not recognized

Legacy method providing string-based access to range bounds. Prefer using GetRange(_range) for type-safe access.

See also: GetRange(_range)

Definition at line 8 of file parameter.cpp.

References range.

◆ GetValue()

double Parameter::GetValue ( )

inline

Get the current parameter value (alternative accessor)

Returns: The current value

See also: Value()

Definition at line 284 of file parameter.h.

References value.

◆ Name()

string Parameter::Name ( ) const

inline

Get the parameter name.

Returns: The parameter's name/identifier

Definition at line 248 of file parameter.h.

References name.

Referenced by SourceSinkData::GetParameterName().

◆ operator=()

Parameter & Parameter::operator= ( const Parameter & param )

Assignment operator.

Parameters

param The Parameter object to copy from

Returns: Reference to this object for chaining

Copies all data from another Parameter object.

Note: Does not copy the current value, only structural information

Definition at line 65 of file parameter.cpp.

References name, prior_distribution, and range.

◆ operator==()

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

Compare parameter with a string (unused, legacy method)

Parameters

dist_type String to compare with

Returns: Comparison result

Deprecated:: This method appears to be unused and may be removed

◆ SetName()

void Parameter::SetName ( const string & nam )

inline

Set the parameter name/identifier.

Parameters

nam	The parameter name (e.g., "Agricultural_Contribution", "Forest_Source")

Parameter names are used for:

Display in GUI and reports
Result file headers
Identifying parameters in optimization output

Definition at line 240 of file parameter.h.

References name.

Referenced by SourceSinkData::InitializeParametersAndObservations().

◆ SetPriorDistribution()

void Parameter::SetPriorDistribution ( distribution_type dist_type )

inline

Set the type of prior probability distribution.

Parameters

dist_type The distribution type to use

Sets the prior distribution type (e.g., normal, lognormal, uniform). Call UpdatePriorDistribution() or SetRange() after this to parameterize the distribution based on the current range.

See also: distribution_type; UpdatePriorDistribution()

Example:

param.SetPriorDistribution(distribution_type::lognormal);

param.SetRange(0.01, 10.0); // Automatically parameterizes lognormal

distribution_type::lognormal

@ lognormal

Lognormal distribution: ln(x) ~ N(μ, σ²), for strictly positive variables.

Definition at line 128 of file parameter.h.

References Distribution::distribution, and prior_distribution.

Referenced by SourceSinkData::InitializeParametersAndObservations().

◆ SetRange() [1/3]

void Parameter::SetRange	(	_range	lowhigh,
		double	value
	)

Set a specific range bound.

Parameters

lowhigh	Specifies which bound to set (low or high)
value	The new bound value

Sets one bound of the range while leaving the other unchanged. Automatically updates the prior distribution parameters to reflect the new range.

Postcondition: Prior distribution is parameterized based on new range; range vector is resized to 2 elements if needed

Example:

param.SetRange(_range::low, 0.05); // Set minimum to 5%

param.SetRange(_range::high, 0.95); // Set maximum to 95%

_range::low

@ low

Lower bound of the parameter range.

_range::high

@ high

Upper bound of the parameter range.

Definition at line 36 of file parameter.cpp.

References low, range, UpdatePriorDistribution(), and value.

◆ SetRange() [2/3]

void Parameter::SetRange ( const vector< double > & rng )

Set the parameter range from a vector.

Parameters

rng	Vector containing [low_bound, high_bound]

Sets both range bounds from a 2-element vector and automatically updates the prior distribution parameters to match the new range.

Precondition: rng.size() must equal 2

Postcondition: Prior distribution is parameterized based on new range

See also: UpdatePriorDistribution()

Definition at line 18 of file parameter.cpp.

References range, and UpdatePriorDistribution().

Referenced by SourceSinkData::InitializeParametersAndObservations().

◆ SetRange() [3/3]

void Parameter::SetRange	(	double	low,
		double	high
	)

Set the parameter range from individual bounds.

Parameters

low	Lower bound of the allowable range
high	Upper bound of the allowable range

Sets the parameter's feasible range and automatically updates the prior distribution parameters. This is the preferred method for setting ranges.

Postcondition: Prior distribution is parameterized based on new range; range vector is resized to 2 elements if needed

Example:

param.SetRange(0.0, 1.0); // Source contribution: 0-100%

Definition at line 48 of file parameter.cpp.

References high, low, range, and UpdatePriorDistribution().

◆ SetValue()

void Parameter::SetValue ( double val )

inline

Set the current parameter value.

Parameters

val	The new value

Sets the parameter's current value, typically during:

MCMC sampling (each iteration)
Genetic algorithm evolution
Optimization convergence

Note: Does not validate that val is within the specified range

Warning: Value may be outside range during optimization algorithms

Definition at line 274 of file parameter.h.

References value.

◆ UpdatePriorDistribution()

void Parameter::UpdatePriorDistribution ( )

Update prior distribution parameters based on current range.

Automatically parameterizes the prior distribution to be consistent with the specified range. Called automatically by SetRange methods.

Parameterization Schemes:

Normal Distribution:

Mean (μ) = midpoint of range = 0.5 × (low + high)
Std dev (σ) = 0.25 × (high - low)
Results in ~95% probability within [low, high] (±2σ)

Lognormal Distribution:

Log-space mean (μ_log) = 0.5 × (ln(low) + ln(high))
Log-space std dev (σ_log) = 0.25 × (ln(high) - ln(low))
Appropriate for strictly positive parameters with multiplicative uncertainty

Other Distributions:

No automatic parameterization (parameters unchanged)

Note: Only affects normal and lognormal distributions

Precondition: range vector must be properly initialized with 2 elements

Postcondition: prior_distribution.parameters vector is updated

See also: SetRange(double, double)

Definition at line 73 of file parameter.cpp.

References Distribution::distribution, log, lognormal, normal, Distribution::parameters, prior_distribution, and range.

Referenced by SetRange(), SetRange(), and SetRange().

◆ Value()

double Parameter::Value ( ) const

inline

Get the current parameter value.

Returns: The current value

See also: GetValue()

Definition at line 258 of file parameter.h.

References value.

Referenced by SourceSinkData::GetElementDistributionMuValue(), SourceSinkData::GetElementDistributionSigmaValue(), and SourceSinkData::GetSourceContributions().

Member Data Documentation

◆ name

string Parameter::name

private

Parameter name/identifier.

Human-readable name used for display, reporting, and identification. Examples: "Agricultural", "Forest", "Urban", "Geological_Baseline"

Definition at line 381 of file parameter.h.

Referenced by Parameter(), Name(), operator=(), and SetName().

◆ prior_distribution

Distribution Parameter::prior_distribution

private

The prior probability distribution for this parameter.

Encodes prior knowledge or beliefs about the parameter's likely values before observing data. Used in Bayesian inference to constrain the posterior distribution.

The distribution is automatically parameterized by UpdatePriorDistribution() based on the specified range for normal and lognormal distributions.

Definition at line 357 of file parameter.h.

Referenced by Parameter(), CalcLogPriorProbability(), GetPriorDistribution(), operator=(), SetPriorDistribution(), and UpdatePriorDistribution().

◆ range

vector<double> Parameter::range

private

Allowable range for the parameter [low, high].

Two-element vector defining the feasible region for optimization and sampling. For source contributions, typically [0.0, 1.0] or [0.0, 100.0].

Range bounds serve multiple purposes:

Hard constraints in optimization algorithms
Basis for automatic prior distribution parameterization
Validity checking in Bayesian inference

Invariant: range.size() == 2; range[0] < range[1] (low < high)

Definition at line 373 of file parameter.h.

Referenced by Parameter(), Parameter(), GetRange(), GetVal(), operator=(), SetRange(), SetRange(), SetRange(), and UpdatePriorDistribution().

◆ value

double Parameter::value = 0

private

Current value of the parameter.

The current estimate or sample value. Updated during:

MCMC sampling (each iteration)
Genetic algorithm evolution (each generation)
Optimization (each step toward minimum)

Default value is 0.0 after construction.

Definition at line 393 of file parameter.h.

Referenced by GetValue(), SetRange(), SetValue(), and Value().

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

Public Member Functions

Private Attributes

Detailed Description

Prior Distribution Parameterization

Constructor & Destructor Documentation

◆ Parameter() [1/2]

◆ Parameter() [2/2]

Member Function Documentation

◆ CalcLogPriorProbability()

◆ GetPriorDistribution()

◆ GetRange()

◆ GetVal()

◆ GetValue()

◆ Name()

◆ operator=()

◆ operator==()

◆ SetName()

◆ SetPriorDistribution()

◆ SetRange() [1/3]

◆ SetRange() [2/3]

◆ SetRange() [3/3]

◆ SetValue()

◆ UpdatePriorDistribution()

Parameterization Schemes:

◆ Value()

Member Data Documentation

◆ name

◆ prior_distribution

◆ range

◆ value