Validation
stochPathSim.validation
Model-validation lab: convergence and discretisation studies, model comparison and HTML reports.
ModelComparison
dataclass
Terminal-distribution statistics of several models and a density overlay figure.
Check
dataclass
One pass/fail test in a report.
ValidationReport
Collects validation studies and writes them to one self-contained HTML file.
rep = ValidationReport("Heston model validation") rep.add_convergence(model, EuropeanCall(100), 1.0, reference=exact, discount=0.03) # doctest: +SKIP rep.to_html("heston_validation.html") # doctest: +SKIP
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
title
|
str
|
Report title. |
'Model validation report'
|
include_plotlyjs
|
('inline', 'cdn')
|
|
"inline"
|
z_threshold
|
float
|
Monte Carlo prices pass when |
3.0
|
p_threshold
|
float
|
Backtest tests pass when their p-value is above this. |
0.05
|
passed
property
passed
True when no check failed.
add_convergence
add_convergence(process, payoff, T, reference, *, label=None, **kwargs)
Monte Carlo convergence against a reference price (see :func:convergence_study).
add_discretisation
add_discretisation(process, payoff, T, reference, *, label=None, **kwargs)
Time-discretisation bias against a reference price (see :func:discretisation_study).
add_comparison
add_comparison(models, T=1.0, *, label=None, **kwargs)
Terminal-distribution comparison of several models (see :func:compare_models).
add_backtest
add_backtest(simulated_distributions, realised, level=0.99, *, label=None, times=None)
Backtest realised values against simulated distributions (one row per date).
Runs the Anderson-Darling uniformity test on the PIT values, the Kupiec test on two-sided
exceedances of the [1 - level, level] quantile band, and Christoffersen's independence test.
add_figure
add_figure(figure, title, description='')
Add any Plotly figure as its own section.
summary
summary()
One row per check: section, check, value, threshold and result.
to_html
to_html(path)
Write the report and return its path.
compare_models
compare_models(models, T=1.0, n_steps=252, n_paths=50000, seed=None, state=None, quantiles=(0.01, 0.05, 0.5, 0.95, 0.99), bins=120, title=None)
Simulate several models on the same horizon and compare their terminal distributions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
models
|
dict
|
|
required |
state
|
str or dict
|
State to compare (default: each model's primary state), or |
None
|
Returns:
| Type | Description |
|---|---|
ModelComparison
|
|
convergence_plot
convergence_plot(df, title=None)
Two panels: price with 95% intervals against the reference, and the error on log-log axes
with the standard error and a 1/sqrt(N) guide.
convergence_study
convergence_study(process, payoff, T, reference, n_paths_list=(1000, 4000, 16000, 64000), *, n_steps=50, seed=None, discount=None, antithetic=False)
Price with an increasing number of paths and compare with a reference value.
Every run uses an independent random stream. For an unbiased estimator the error
shrinks like 1/sqrt(n_paths) and the z-scores error / stderr stay within a few units.
Returns a DataFrame with columns n_paths, price, stderr, error, abs_error, z_score;
attrs["reference"] holds the reference value.
discretisation_plot
discretisation_plot(df, title=None)
|bias| against the step size on log-log axes, with the 3-standard-error noise floor.
discretisation_study
discretisation_study(process, payoff, T, reference, n_steps_list=(4, 8, 16, 32, 64), *, n_paths=100000, seed=None, discount=None, antithetic=True)
Measure the time-discretisation bias of a scheme.
process is a process, or a callable n_steps -> process for schemes whose parameters
depend on the step. All runs share the same seed so the statistical noise is similar.
Returns a DataFrame with columns n_steps, dt, price, stderr, bias, abs_bias, significant
(|bias| > 3 stderr). attrs["weak_order"] is the log-log slope of |bias| against
dt over the significant points (NaN if fewer than two), an estimate of the weak order.
compare
Side-by-side comparison of models.
ModelComparison
dataclass
Terminal-distribution statistics of several models and a density overlay figure.
compare_models
compare_models(models, T=1.0, n_steps=252, n_paths=50000, seed=None, state=None, quantiles=(0.01, 0.05, 0.5, 0.95, 0.99), bins=120, title=None)
Simulate several models on the same horizon and compare their terminal distributions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
models
|
dict
|
|
required |
state
|
str or dict
|
State to compare (default: each model's primary state), or |
None
|
Returns:
| Type | Description |
|---|---|
ModelComparison
|
|
convergence
Monte Carlo convergence and time-discretisation studies.
convergence_study
convergence_study(process, payoff, T, reference, n_paths_list=(1000, 4000, 16000, 64000), *, n_steps=50, seed=None, discount=None, antithetic=False)
Price with an increasing number of paths and compare with a reference value.
Every run uses an independent random stream. For an unbiased estimator the error
shrinks like 1/sqrt(n_paths) and the z-scores error / stderr stay within a few units.
Returns a DataFrame with columns n_paths, price, stderr, error, abs_error, z_score;
attrs["reference"] holds the reference value.
convergence_plot
convergence_plot(df, title=None)
Two panels: price with 95% intervals against the reference, and the error on log-log axes
with the standard error and a 1/sqrt(N) guide.
discretisation_study
discretisation_study(process, payoff, T, reference, n_steps_list=(4, 8, 16, 32, 64), *, n_paths=100000, seed=None, discount=None, antithetic=True)
Measure the time-discretisation bias of a scheme.
process is a process, or a callable n_steps -> process for schemes whose parameters
depend on the step. All runs share the same seed so the statistical noise is similar.
Returns a DataFrame with columns n_steps, dt, price, stderr, bias, abs_bias, significant
(|bias| > 3 stderr). attrs["weak_order"] is the log-log slope of |bias| against
dt over the significant points (NaN if fewer than two), an estimate of the weak order.
discretisation_plot
discretisation_plot(df, title=None)
|bias| against the step size on log-log axes, with the 3-standard-error noise floor.
report
Self-contained HTML model-validation reports.
Check
dataclass
One pass/fail test in a report.
ValidationReport
Collects validation studies and writes them to one self-contained HTML file.
rep = ValidationReport("Heston model validation") rep.add_convergence(model, EuropeanCall(100), 1.0, reference=exact, discount=0.03) # doctest: +SKIP rep.to_html("heston_validation.html") # doctest: +SKIP
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
title
|
str
|
Report title. |
'Model validation report'
|
include_plotlyjs
|
('inline', 'cdn')
|
|
"inline"
|
z_threshold
|
float
|
Monte Carlo prices pass when |
3.0
|
p_threshold
|
float
|
Backtest tests pass when their p-value is above this. |
0.05
|
passed
property
passed
True when no check failed.
add_convergence
add_convergence(process, payoff, T, reference, *, label=None, **kwargs)
Monte Carlo convergence against a reference price (see :func:convergence_study).
add_discretisation
add_discretisation(process, payoff, T, reference, *, label=None, **kwargs)
Time-discretisation bias against a reference price (see :func:discretisation_study).
add_comparison
add_comparison(models, T=1.0, *, label=None, **kwargs)
Terminal-distribution comparison of several models (see :func:compare_models).
add_backtest
add_backtest(simulated_distributions, realised, level=0.99, *, label=None, times=None)
Backtest realised values against simulated distributions (one row per date).
Runs the Anderson-Darling uniformity test on the PIT values, the Kupiec test on two-sided
exceedances of the [1 - level, level] quantile band, and Christoffersen's independence test.
add_figure
add_figure(figure, title, description='')
Add any Plotly figure as its own section.
summary
summary()
One row per check: section, check, value, threshold and result.
to_html
to_html(path)
Write the report and return its path.