Output

output

MCMC Output Tracking.

Outputs generally consist of two components: a Quantity of Interest (QoI), which is computed solely from the samples, and a statistic, which is derived from the QoI.

For example, to track the acceptance rate, the QoI could be "Was the sample accepted?". A corresponding statistic might be the average acceptance over the last 100 samples, or the overall average across all samples.

This module implements some basic QoIs and statistics.

Classes:

Name	Description
MCMCQoI	Abstract base class of Quantity of Interest
MCMCStatistic	Abstract base class for statistics
MCMCOutput	Output object that combines a QoI and statistic
SimplifiedMCMCOutput	MCMCOutput that autoconfigures as much as possible
ComponentQoi	A specific component of the state as a QoI
MeanQoI	The mean as a QoI
AcceptanceQoI	The acceptance as a QoI
IdentityStatistic	Identity as a statistic
RunningMeanStatistic	A running mean as a statistic
BatchMeanStatistic	A batch mean as a statistic
Acceptance	Preconfigured output that tracks the running mean of the acceptance

ls_mcmc.output.MCMCQoI

Bases: ABC

Abstract base class for Quantities of Interest (QoI) in MCMC sampling.

Methods:

Name	Description
evaluate	Calculate QoI from state vector
name	Name of the QoI

evaluate abstractmethod

evaluate(state: np.ndarray[tuple[int], np.dtype[np.floating]], accepted: bool) -> Number

Evaluates QoI from state vector.

Parameters:

Name	Type	Description	Default
state	np.ndarray[tuple[int], np.dtype[np.floating]]	Current state vector from MCMC chain.	required
accepted	bool	Whether the current proposal was accepted.	required

Returns:

Type	Description
Number	Evaluated quantity of interest value

name abstractmethod

name() -> str

Returns the name of the quantity of interest.

__str__

__str__() -> str

Name of the QoI for logging the output.

ls_mcmc.output.ComponentQoI

Bases: MCMCQoI

QoI that extracts a specific component from the state vector.

Methods:

Name	Description
evaluate	Calculate QoI from state vector
name	Name of the QoI

__init__

__init__(component: int) -> None

Initialize ComponentQoI.

Parameters:

Name	Type	Description	Default
component	int	Index of the component to extract from state vector.	required

evaluate

evaluate(state: np.ndarray[tuple[int], np.dtype[np.floating]], _accepted: bool) -> float

Extracts specified component from state.

name

name() -> str

String representation of the form "component " used for logging.

ls_mcmc.output.MeanQoI

Bases: MCMCQoI

QoI that computes the mean of all components in the state vector.

Methods:

Name	Description
evaluate	Calculate QoI from state vector
name	Name of the QoI

evaluate staticmethod

evaluate(state: np.ndarray[tuple[int], np.dtype[np.floating]], _: bool) -> float

Extracts mean of the state.

name staticmethod

name() -> str

String "mean" used for logging the output.

ls_mcmc.output.AcceptanceQoI

Bases: MCMCQoI

QoI that tracks proposal acceptance status.

Methods:

Name	Description
evaluate	Calculate QoI from state vector
name	Name of the QoI

evaluate staticmethod

evaluate(_: np.ndarray[tuple[int], np.dtype[np.floating]], accepted: bool) -> float

Extracts whether a state was accepted or not and converts to float for calculations.

name staticmethod

name() -> str

String "acceptance" used for logging the output.

ls_mcmc.output.MCMCStatistic

Bases: ABC

Abstract base class for statistics computed from QoI values.

Methods:

Name	Description
evaluate	Calculate statistic from a Quantity of Interest
name	Name of the Statistic

evaluate abstractmethod

evaluate(qoi_value: Number) -> Number

Evaluates a certain statistic from a Quantity of Interest.

Parameters:

Name	Type	Description	Default
qoi_value	Number	Value from a quantity of interest evaluation	required

Returns:

Type	Description
Number	Computed statistic value.

name abstractmethod

name() -> str

Returns the name of the statistic.

__str__

__str__() -> str

Name of the Statistic used for logging.

ls_mcmc.output.IdentityStatistic

Bases: MCMCStatistic

Statistic that returns the input value unchanged.

Methods:

Name	Description
evaluate	Calculate statistic from a Quantity of Interest
name	Name of the Statistic

evaluate staticmethod

evaluate(qoi_value: Number) -> Number

Returns the QoI unchanged.

name staticmethod

name() -> str

String "identity" for logging the output.

ls_mcmc.output.RunningMeanStatistic

Bases: MCMCStatistic

Statistic that computes a running mean of QoI values.

Methods:

Name	Description
evaluate	Calculate statistic from a Quantity of Interest
name	Name of the Statistic

__init__

__init__() -> None

Initialize running mean.

evaluate

evaluate(qoi_value: Number) -> float

Updates the running mean based on a new sample QoI.

name

name() -> str

String "mean" for logging the output.

ls_mcmc.output.BatchMeanStatistic

Bases: MCMCStatistic

Statistic that computes the mean of QoI values in batches.

Methods:

Name	Description
evaluate	Calculate statistic from a Quantity of Interest
name	Name of the Statistic

__init__

__init__(batch_size: int) -> None

Initialize BatchMeanStatistic.

Parameters:

Name	Type	Description	Default
batch_size	int	Number of samples per batch	required

Raises:

Type	Description
ValueError	If batch_size is less than or equal to zero.

evaluate

evaluate(qoi_value: Number) -> float

Updates the batch mean based on a new sample QoI.

name

name() -> str

String "BM" for logging the output.

ls_mcmc.output.MCMCOutput

Combines a QoI and statistic for MCMC output tracking and logging.

Methods:

Name	Description
update	update output based on a new state
value	return most recent output value
values	return all output values

value property

value: Number

Returns the most recent output value.

all_values property

all_values: np.ndarray[tuple[int], np.dtype[np.floating]]

Returns all computed output values as numpy array.

__init__

__init__(qoi: MCMCQoI, statistic: MCMCStatistic, str_id: str | None = None, str_format: str | None = None, log: bool = False) -> None

Initialize MCMCOutput.

Parameters:

Name	Type	Description	Default
qoi	MCMCQoI	Quantity of interest to evaluate	required
statistic	MCMCStatistic	Statistic to compute from QoI values	required
str_id	str | None	String identifier for logging. Required if log=True	None
str_format	str | None	Format string for logging. Required if log=True	None
log	bool	Whether to include this output in logging	False

Raises:

Type	Description
ValueError	If log=True but str_id or str_format is None.

update

update(state: np.ndarray[tuple[int], np.dtype[np.floating]], accepted: bool) -> None

Update output with new MCMC state.

Parameters:

Name	Type	Description	Default
state	np.ndarray[tuple[int], np.dtype[np.floating]]	Current state vector from MCMC chain	required
accepted	bool	Whether the current proposal was accepted	required

ls_mcmc.output.Acceptance

Bases: MCMCOutput

Pre-configured output for tracking average acceptance rate.

Methods:

Name	Description
update	update output based on a new state
value	return most recent output value
values	return all output values

__init__

__init__() -> None

Initialize acceptance output.

ls_mcmc.output.SimplifiedOutput

Bases: MCMCOutput

Simplified output constructor with automatic string formatting.

Methods:

Name	Description
update	update output based on a new state
value	return most recent output value
values	return all output values

__init__

__init__(qoi: MCMCQoI, statistic: MCMCStatistic) -> None

Initialize SimplifiedOutput with automatic formatting.

Parameters:

Name	Type	Description	Default
qoi	MCMCQoI	Quantity of interest to evaluate.	required
statistic	MCMCStatistic	Statistic to compute from QoI values.	required