MCModel

MCModel()

Lazy Monte Carlo expression composed from distributions, constants, and models.

MCModel is intentionally not a Distribution: composed Monte Carlo expressions are sampleable, but generally do not have closed-form density, CDF, or inverse-CDF methods.

Attributes

Name	Description
model_config	dict() -> new empty dictionary

Methods

Name	Description
add_copula	Attach a copula to this model for correlated sampling.
clear_cache	Clear cached simulation results from this model.
correlate	Attach a Gaussian copula using this model’s distribution leaves.
distributions	Return unique distribution leaves used by this model, in expression order.
from_operation	Build a lazy model expression from an operation and operands.
plot	Plot an empirical CDF with a low-alpha histogram on a secondary axis.
plot_sensitivity	Plot a one-at-a-time sensitivity tornado chart for this model.
rvs	Alias for :meth:sample for users familiar with SciPy naming.
sample	Evaluate the model by sampling distribution leaves and applying operations.
sensitivity	Run one-at-a-time sensitivity analysis over distribution leaves.
sensitivity_analysis	Return a serializable one-at-a-time sensitivity analysis object.
summary	Summarize simulated model outcomes as a tidy dataframe.
where	Build a lazy model expression equivalent to numpy.where.

add_copula

MCModel.add_copula(copula)

Attach a copula to this model for correlated sampling.

The copula is used by :meth:sample, :meth:summary, and :meth:plot. Distributions covered by the copula are sampled jointly; model distributions not included in the copula continue to be sampled independently. The copula may only reference distributions that are present in this model expression.

clear_cache

MCModel.clear_cache()

Clear cached simulation results from this model.

correlate

MCModel.correlate(correlation)

Attach a Gaussian copula using this model’s distribution leaves.

correlation may be a single off-diagonal correlation value or a full correlation matrix. Matrix rows/columns are interpreted in the order returned by :meth:distributions, i.e. first appearance in the model expression.

distributions

MCModel.distributions()

Return unique distribution leaves used by this model, in expression order.

from_operation

MCModel.from_operation(op, *operands, name=None)

Build a lazy model expression from an operation and operands.

plot

MCModel.plot(
    ax=None,
    *,
    size=None,
    seed=None,
    refresh=False,
    bins=80,
    show=False,
    x_quantile_range=(0.001, 0.999),
    ecdf_kwargs=None,
    hist_kwargs=None,
    percentile_guides=True,
    percentiles=DEFAULT_PERCENTILES,
    percentile_guide_kwargs=None,
    **kwargs,
)

Plot an empirical CDF with a low-alpha histogram on a secondary axis.

Returns the primary Matplotlib Axes object. Extra keyword arguments are passed to the ECDF line for convenient calls like model.plot(color="steelblue"). By default, the x-axis is limited to the 0.001 and 0.999 sample quantiles; pass x_quantile_range=None to show the full sampled range or another (low, high) quantile pair to customize it. Cached samples are reused by default when available.

plot_sensitivity

MCModel.plot_sensitivity(
    ax=None,
    *,
    percentiles=DEFAULT_PERCENTILES,
    center_percentile=50,
    precision=2,
    show=False,
    positive_color='seagreen',
    negative_color='firebrick',
    baseline_kwargs=None,
    bar_kwargs=None,
    line_kwargs=None,
)

Plot a one-at-a-time sensitivity tornado chart for this model.

rvs

MCModel.rvs(size=1, *, seed=None, refresh=False)

Alias for :meth:sample for users familiar with SciPy naming.

sample

MCModel.sample(size=1, *, seed=None, refresh=False)

Evaluate the model by sampling distribution leaves and applying operations.

A single shared random number generator is passed through all distribution samples so a seeded model is reproducible while each distribution consumes a distinct part of the random stream. Reused distribution/model objects are cached within one evaluation, preserving sample-wise dependence: x + x uses the same draws from x on both sides.

sensitivity

MCModel.sensitivity(
    percentiles=DEFAULT_PERCENTILES,
    center_percentile=50,
    precision=2,
)

Run one-at-a-time sensitivity analysis over distribution leaves.

The baseline fixes every distribution leaf to center_percentile. Each distribution is then varied through percentiles while all other distribution leaves remain fixed at the centre value. Constants are not included as sensitivity variables.

sensitivity_analysis

MCModel.sensitivity_analysis(
    percentiles=DEFAULT_PERCENTILES,
    center_percentile=50,
    precision=2,
)

Return a serializable one-at-a-time sensitivity analysis object.

summary

MCModel.summary(
    size=None,
    seed=None,
    refresh=False,
    threshold=None,
    conditional_on_threshold=False,
    percentiles=DEFAULT_PERCENTILES,
    precision=2,
)

Summarize simulated model outcomes as a tidy dataframe.

The summary includes the mean, configurable descending percentiles, and optionally the probability that simulated values exceed threshold. When conditional_on_threshold is true, the mean and percentile values are calculated only from values exceeding threshold and are explicitly labeled with that condition. Values are rounded to precision decimal places by default; pass precision=None to return unrounded values. Cached samples are reused by default when available.

where

MCModel.where(condition, x, y, *, name=None)

Build a lazy model expression equivalent to numpy.where.