2.2.3. sdepy.montecarlo

class sdepy.montecarlo(sample=None, axis=-1, bins=100, range=None, use='all', dtype=None, ctype=<class 'numpy.int64'>)[source]

Summary statistics of Monte Carlo simulations.

Compute, store and cumulate results of Monte Carlo simulations across multiple runs. Cumulated results include mean, standard deviation, standard error, skewness, kurtosis, and 1d-histograms of the distribution of outcomes. Probability distribution function estimates are provided, based on the cumulated histograms.

Parameters:
sample : array-like, optional

Initial data set to be summarized. If None, an empty instance is provided, initialized with the given parameters.

axis : integer, optional

Axis of the given sample enumerating single data points (paths, or different realizations of a simulated process or event). Defaults to the last axis of the sample.

use : {‘all’, ‘even’, ‘odd’}, optional

If 'all' (default), the data set is processed as is. If 'even' or 'odd', the sample x is assumed to consist of antithetic values along the specified axis, assumed of even size 2*N, where x[0], x[1], ... is antithetic respectively to x[N], x[N+1], .... Summary operations are then applied to a sample of size N consisting of the half-sum ('even') or half-difference ('odd') of antithetic values.

bins : array-like, or int, or str, optional

Bins used to evaluate the counts’ cumulated distribution are computed, against the first data set encountered, according to the bins parameter:

  • If int or str, it dictates the number of bins or their determination method, as passed to numpy.histogram when processing the first sample.
  • If array-like, overrides range, setting explicit bins’ boundaries, so that bins[i][j] is the lower bound of the j-th bin used for the distribution of the i-th component of data points.
  • If None, no distribution data will be computed.

Defaults to 100.

range : (float, float) or None, optional

Bins range specification, as passed to numpy.histogram.

dtype : data-type, optional

Data type used for cumulating moments. If None, the data-type of the first sample is used, if of float kind, or float otherwise.

ctype : data-type, optional

Data type used for cumulating histogram counts. Defaults to numpy.int64.

Notes

The shape of cumulated statistics is set as the shape of the data points of the first data set processed (shape of the first sample after summarizing along the paths axis). When cumulating subsequent samples, broadcasting rules apply.

Indexing can be used to access single values or slices of the stored data. Given a montecarlo instance a, a[i] is a new instance referencing statistics of the i-th component of data summarized in a (no copying).

The first data set encountered fixes the histogram bins. Points of subsequent data sets that fall outside the bins, while properly taken into account in summary statistics (mean, standard error etc.), are ignored when building cumulated histograms and probability distribution functions. Their number is accounted for in the outpaths property and outerr method.

Histograms and distributions, and the related outpaths and outerr, must be invoked on single-valued montecarlo instances. For multiple valued simulations, use indexing to select the value to be addressed (e.g. a[i].histogram()).

Attributes:
paths

Number of cumulated sample data points (0 for an empty instance).

vshape

Shape of cumulated sample data points.

shape

Shape of cumulated sample data set, rearranged with averaging axis as last axis.

outpaths

Data points fallen outside of the bins’ boundaries.

m

Shortcut for the mean method.

s

Shortcut for the std method.

e

Shortcut for the stderr method.

stats

Dictionary of cumulated statistics.

h

Shortcut for the histogram method.

dh

Shortcut for the density_histogram method.

Methods

update(sample[, axis]) Add the given sample to the montecarlo simulation.
mean() Mean of cumulated sample data points.
var() Variance of cumulated sample data points.
std() Standard deviation of cumulated sample data points.
skew() Skewness of cumulated sample data points.
kurtosis() Kurtosis of cumulated sample data points.
stderr() Standard error of the mean of cumulated sample data points.
histogram() Distribution of the cumulated sample data, as a counts histogram.
density_histogram() Distribution of the cumulated sample data, as a normalized counts histogram.
pdf(x[, method, bandwidth, kind]) Normalized sample probability density function, evaluated at x.
cdf(x[, method, bandwidth, kind]) Cumulative sample probability density function, evaluated at x.
outerr() Fraction of cumulated data points fallen outside of the bins’ boundaries.