QuantileMatchingFactory

class QuantileMatchingFactory(*args)

Estimation by matching quantiles.

Implements generic estimation by matching quantiles.

Parameters:
distributionDistribution

The distribution defining the parametric model to be adjusted to data. Its parameters define the starting point of the algorithm.

probabilitiesincreasing sequence of float in [0, 1]

The probabilities p_i \in [0,1] corresponding to the quantiles. At most K values can be given. It is possible to provide less than K values if setKnownParameter() is used

boundsInterval, optional

Parameter bounds. The default bounds is an empty interval, which implies that the optimization problem is unbounded.

Notes

We consider a parametric model whose cumulative distribution function F_{\vect{\theta}} is parametrized by \vect{\theta} \in \Rset^K.

Given a set of probabilities p_1, ..., p_K \in [0, 1] and a set of scalars q_1, ..., q_K \in \Rset, we want to determine \vect{\theta} such that q_i be the quantile of order p_i of F_{\vect{\theta}}:

F_{\vect{\theta}}(q_i) = p_i, \quad 1 \leq i \leq K

This is useful when some expert is able to specify such quantiles.

When the quantiles q_i are not known, they can be deduced from a given sample. We denote \hat{q}_1, ..., \hat{q}_K the empirical quantiles obtained. In that case, we want to determine \vect{\theta} such that \hat{q}_i be the quantile of order p_i of F_{\vect{\theta}}:

F_{\vect{\theta}}(\hat{q}_i) = p_i, \quad 1 \leq i \leq K

The optimal \vect{\theta} is searched as the solution of the optimization problem:

\vect{\theta}_{opt} = \argmin_{\vect{\theta} \in \Rset^K} \sum_{i=1}^K (F^{-1}_{\vect{\theta}}(p_i) - \hat{q}_i)^2

Examples

Fit a distribution with 2 parameters. Hence, two quantiles are used to estimate the parameters. Here, both quantiles are estimated from a given sample.

>>> import openturns as ot
>>> ot.RandomGenerator.SetSeed(0)
>>> sample = ot.Normal(0.9, 1.7).getSample(10)
>>> factory = ot.QuantileMatchingFactory(ot.Normal(), [0.01, 0.99])
>>> inf_distribution = factory.build(sample)
>>> print(inf_distribution)
Normal(mu = 0.267484, sigma = 1.32218)
>>> print(factory.getProbabilities())
[0.01,0.99]

We see that the default value of the \epsilon parameter is so that we consider the 1% and 99% percentile ranks.

Use 5% and 95% percentile ranks:

>>> probabilities = [0.05, 0.95]
>>> factory = ot.QuantileMatchingFactory(ot.Normal(), probabilities)
>>> inf_distribution = factory.build(sample)

We can also make the optimization problem easier by specifying bounds to the parameters:

>>> bounds = ot.Interval([-0.1, 0.0], [1.0, 2.0])
>>> factory = ot.QuantileMatchingFactory(ot.Normal(), probabilities, bounds)
>>> inf_distribution = factory.build(sample)

An example with 4 parameters:

>>> # A distribution with 4 parameters
>>> distribution = ot.Beta(2.0, 3.0, 4.0, 5.0)
>>> sample = distribution.getSample(10)
>>> distribution = ot.Beta()
>>> factory = ot.QuantileMatchingFactory(distribution, [0.01, 1/3, 2/3, 0.99])
>>> inf_distribution = factory.build(sample)

Methods

build(*args)

Build the distribution.

buildEstimator(*args)

Build the distribution and the parameter distribution.

buildFromQuantiles(quantiles)

Build from given quantiles.

getBootstrapSize()

Accessor to the bootstrap size.

getClassName()

Accessor to the object's name.

getId()

Accessor to the object's id.

getKnownParameterIndices()

Accessor to the known parameters indices.

getKnownParameterValues()

Accessor to the known parameters indices.

getName()

Accessor to the object's name.

getOptimizationAlgorithm()

Accessor to the solver.

getOptimizationBounds()

Accessor to the optimization bounds.

getProbabilities()

Accessor to the probabilities.

getShadowedId()

Accessor to the object's shadowed id.

getVisibility()

Accessor to the object's visibility state.

hasName()

Test if the object is named.

hasVisibleName()

Test if the object has a distinguishable name.

setBootstrapSize(bootstrapSize)

Accessor to the bootstrap size.

setKnownParameter(values, positions)

Accessor to the known parameters.

setName(name)

Accessor to the object's name.

setOptimizationAlgorithm(solver)

Accessor to the solver.

setOptimizationBounds(optimizationBounds)

Accessor to the optimization bounds.

setProbabilities(probabilities)

Accessor to the fractiles.

setShadowedId(id)

Accessor to the object's shadowed id.

setVisibility(visible)

Accessor to the object's visibility state.

__init__(*args)
build(*args)

Build the distribution.

Available usages:

build()

build(sample)

build(param)

Parameters:
sample2-d sequence of float

Data.

paramsequence of float

The parameters of the distribution.

Returns:
distDistribution

The estimated distribution.

In the first usage, the default native distribution is built.

buildEstimator(*args)

Build the distribution and the parameter distribution.

Parameters:
sample2-d sequence of float

Data.

parametersDistributionParameters

Optional, the parametrization.

Returns:
resDistDistributionFactoryResult

The results.

Notes

According to the way the native parameters of the distribution are estimated, the parameters distribution differs:

  • Moments method: the asymptotic parameters distribution is normal and estimated by Bootstrap on the initial data;

  • Maximum likelihood method with a regular model: the asymptotic parameters distribution is normal and its covariance matrix is the inverse Fisher information matrix;

  • Other methods: the asymptotic parameters distribution is estimated by Bootstrap on the initial data and kernel fitting (see KernelSmoothing).

If another set of parameters is specified, the native parameters distribution is first estimated and the new distribution is determined from it:

  • if the native parameters distribution is normal and the transformation regular at the estimated parameters values: the asymptotic parameters distribution is normal and its covariance matrix determined from the inverse Fisher information matrix of the native parameters and the transformation;

  • in the other cases, the asymptotic parameters distribution is estimated by Bootstrap on the initial data and kernel fitting.

buildFromQuantiles(quantiles)

Build from given quantiles.

Parameters:
quantilesincreasing sequence of float

The quantiles of the distribution, matching the probabilities provided to the constructor.

Returns:
distDistribution

The estimated distribution.

getBootstrapSize()

Accessor to the bootstrap size.

Returns:
sizeinteger

Size of the bootstrap.

getClassName()

Accessor to the object’s name.

Returns:
class_namestr

The object class name (object.__class__.__name__).

getId()

Accessor to the object’s id.

Returns:
idint

Internal unique identifier.

getKnownParameterIndices()

Accessor to the known parameters indices.

Returns:
indicesIndices

The indices of the fixed parameters.

getKnownParameterValues()

Accessor to the known parameters indices.

Returns:
valuesPoint

The values of the fixed parameters.

getName()

Accessor to the object’s name.

Returns:
namestr

The name of the object.

getOptimizationAlgorithm()

Accessor to the solver.

Returns:
solverOptimizationAlgorithm

The solver used for numerical optimization of the moments.

getOptimizationBounds()

Accessor to the optimization bounds.

Returns:
boundsInterval

The bounds used for numerical optimization of the likelihood.

getProbabilities()

Accessor to the probabilities.

Returns:
probabilitiesPoint

The probabilities p_i.

getShadowedId()

Accessor to the object’s shadowed id.

Returns:
idint

Internal unique identifier.

getVisibility()

Accessor to the object’s visibility state.

Returns:
visiblebool

Visibility flag.

hasName()

Test if the object is named.

Returns:
hasNamebool

True if the name is not empty.

hasVisibleName()

Test if the object has a distinguishable name.

Returns:
hasVisibleNamebool

True if the name is not empty and not the default one.

setBootstrapSize(bootstrapSize)

Accessor to the bootstrap size.

Parameters:
sizeinteger

The size of the bootstrap.

setKnownParameter(values, positions)

Accessor to the known parameters.

Parameters:
valuessequence of float

Values of fixed parameters.

indicessequence of int

Indices of fixed parameters.

Notes

Using this method may cause the class to ignore some values of the given probabilities (or the default ones) as the underlying least squares problem is solved in dimension K minus the number of known parameters.

Examples

>>> import openturns as ot
>>> ot.RandomGenerator.SetSeed(0)
>>> distribution = ot.Beta(2.3, 2.2, -1.0, 1.0)
>>> sample = distribution.getSample(10)
>>> factory = ot.QuantileMatchingFactory(ot.Beta(), [0.01, 0.99])
>>> # set (a,b) out of (r, t, a, b)
>>> factory.setKnownParameter([-1.0, 1.0], [2, 3])
>>> inf_distribution = factory.build(sample)
setName(name)

Accessor to the object’s name.

Parameters:
namestr

The name of the object.

setOptimizationAlgorithm(solver)

Accessor to the solver.

Parameters:
solverOptimizationAlgorithm

The solver used for numerical optimization of the moments.

setOptimizationBounds(optimizationBounds)

Accessor to the optimization bounds.

Parameters:
boundsInterval

The bounds used for numerical optimization of the likelihood.

setProbabilities(probabilities)

Accessor to the fractiles.

Parameters:
probabilitiessequence of float

The probabilities p_i.

setShadowedId(id)

Accessor to the object’s shadowed id.

Parameters:
idint

Internal unique identifier.

setVisibility(visible)

Accessor to the object’s visibility state.

Parameters:
visiblebool

Visibility flag.

Examples using the class

Define a distribution from quantiles

Define a distribution from quantiles