Previous: Distribution Fitting | Technical Reference | Next: Composite Analysis
UnivariateAnalysis is the analysis-layer workflow for one UnivariateDistribution. It validates the model and sampler, prepares observation and prior structures, runs Bayesian MCMC, and converts retained parameter draws into frequency and—when applicable—nonstationary chronology results. The analysis is Bayesian-first: a frequency curve is a posterior-derived quantity, not an MLE curve with an attached generic confidence band.
Let DataFrame, Parameters, and
Equivalently, the implemented log target is
where
For a stationary distribution with CDF
ProbabilityOrdinates stores
RunAsync performs the following implemented sequence:
- Validate the
UnivariateDistribution,ProbabilityOrdinates, andBayesianAnalysissettings. - Raise the cancellable preview event and establish a new cancellation source.
- Wait for any in-flight result-only reprocessing, then clear prior MCMC and derived results.
- Reprocess perception-threshold records; for a nonstationary model, construct the full indexed time series.
- Transform configured quantile priors into the representation consumed by the likelihood.
- Run
BayesianAnalysisagainst the complete posterior target. - If MCMC succeeds, construct frequency results and, for a nonstationary model, chronology results.
- Mirror the inner Bayesian estimator's success state and raise a completion event carrying success, cancellation, or exception information.
CancelAnalysis() cancels both the outer analysis and the sampler. Exceptions raised inside the workflow are reported through the completion event; callers should inspect IsEstimated, BayesianAnalysis.IsEstimated, and non-null results rather than assuming that an awaited task necessarily produced a fit.
The code below is compiled against the current API. Production studies should set the sampler configuration deliberately and assess convergence as described in Bayesian MCMC.
private static async Task<UnivariateAnalysis> RunValidatedAnalysis(
UnivariateDistribution model)
{
var analysis = new UnivariateAnalysis(model);
var validation = analysis.Validate();
if (!validation.IsValid)
{
throw new InvalidOperationException(
string.Join(Environment.NewLine, validation.ValidationMessages));
}
await analysis.RunAsync();
if (!analysis.IsEstimated || analysis.AnalysisResults is null)
{
throw new InvalidOperationException(
"The analysis did not produce uncertainty results.");
}
return analysis;
}This method intentionally does not prescribe iteration counts. The defensible count depends on posterior geometry, tail functionals, effective sample size, and convergence diagnostics—not a universal constant.
Let retained MCMC draws be
For a stationary model, each draw is applied to a clone of the parent Numerics distribution. For a nonstationary model, each full trend-parameter draw is applied to a cloned UnivariateDistribution, and the exposed distribution at ParameterTimeIndex is retained. AnalysisResults then summarizes the empirical distribution of CredibleIntervalWidth is the retained posterior probability between those limits; changing it recomputes summaries without rerunning MCMC.
The displayed point-estimate curve is selected by BayesianAnalysis.PointEstimator:
PosteriorMeanapplies the componentwise mean of retained parameter draws.PosteriorModeapplies the saved draw with the highest posterior target (MCMCResults.MAP).
Neither curve is generally equal to the posterior mean of the quantile because
Use the posterior quantile distribution, not only the point curve, for risk calculations.
For an indexed covariate or time value
where UnivariateDistribution.Alpha selects
Changing ParameterTimeIndex reprocesses frequency results from the existing chain. Crossing the observed-record boundary also refreshes the chronology extent. Changing the chronology AEP reprocesses chronology output. Structural changes—data, family, parameters, trend models, and prior settings—clear the fit and require new MCMC.
Grouped perception-threshold periods use the deterministic disaggregation assumptions documented in Data Frame and Mixed-Observation Likelihood. In addition, coefficient priors apply to the stored trend coefficients, while distribution-dependent Jeffreys and quantile-prior terms are evaluated once at the last, most-recent observed index as documented in Parameters, Bounds, and Priors. Consequently, nonstationary posterior and chronology results are conditional on both the grouped-threshold allocation and the final-time prior reference.
UpdatePointEstimateResultsAsync() computes the displayed AIC and BIC from UnivariateDistribution.DataLogLikelihood(...) evaluated at the stored MAP parameter vector; parameter, Jeffreys, and quantile-prior densities are excluded. When every active prior is constant over the relevant parameter region, MAP coincides with the constrained MLE and these values are comparable with the fitting-analysis criteria. With any informative or otherwise nonconstant prior—including the optional Jeffreys scale term—the MAP is prior-influenced and these fields should not be interpreted as conventional AIC/BIC. Use DIC, WAIC, or verified PSIS-LOO for Bayesian comparison in that setting. See Model Comparison for the interpretation of these criteria.
The displayed RMSE uses the pinned Numerics root-mean-square-error helper.
ToXElement() stores the outer estimated flag, probability ordinates, and BayesianAnalysis configuration/result metadata. It does not serialize the model, raw data, AnalysisResults, or ChronologyAnalysisResults in the same element. The restoring constructor therefore accepts the UnivariateDistribution and optionally accepts MCMCResults and the two uncertainty-result objects. If complete Bayesian and frequency artifacts are restored from an older save, the constructor normalizes a stale outer estimated flag.
- Posterior statements are conditional on the selected family, trend structure, observation model, prior distributions, and data preprocessing.
- Independent observation contributions are assumed by the pointwise WAIC/LOO representation. Serial dependence, duplicated events, and unmodeled spatial dependence invalidate the nominal decomposition.
- A low tail probability can be much farther beyond the information in the record than its compact AEP notation suggests. Report posterior uncertainty and sensitivity to family/prior choices.
- Parameterwise posterior means can violate nonlinear structural interpretations even when they remain inside scalar bounds; inspect the resulting distribution.
- Credible intervals quantify posterior uncertainty under the model. They are not frequentist coverage guarantees and do not include unmodeled measurement, process, or model-form uncertainty.
- MCMC completion is not convergence. Review rank-normalized
$\widehat R$ , effective sample size, chain behavior, boundary contact, and tail-functional stability.
| Concern | Implementation |
|---|---|
| Analysis lifecycle | Analyses/Univariate/UnivariateAnalysis.cs |
| Statistical model | Models/UnivariateDistribution/UnivariateDistribution.cs |
| Sampler orchestration | Estimation/BayesianAnalysis.cs |
| MCMC results | pinned Numerics/Sampling/MCMC/MCMCResults.cs |
| Frequency uncertainty aggregation | pinned Numerics/Distributions/Univariate/Uncertainty Analysis/UncertaintyAnalysisResults.cs |
| Compiled example | RMC.BestFit.Tests/Documentation/Examples/AnalysisExamples.cs |
[1] A. Gelman et al., Bayesian Data Analysis, 3rd ed. Boca Raton, FL, USA: CRC Press, 2013.
[2] S. Coles, An Introduction to Statistical Modeling of Extreme Values. London, U.K.: Springer, 2001.
[3] A. Vehtari et al., “Rank-normalization, folding, and localization: An improved
Previous: Distribution Fitting | Technical Reference | Next: Composite Analysis