diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 329dc35..551394e 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-30T14:22:40","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-01T08:28:18","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/dev/api/index.html b/dev/api/index.html index 56d4502..0f22d92 100644 --- a/dev/api/index.html +++ b/dev/api/index.html @@ -1,5 +1,5 @@ API · DistributionFits.jl
GitHub

API

AbstractMoments

The concept of first and higher order moments is captured by its own type. This allows dispatching the fit method.

DistributionFits.AbstractMoments — Type
AbstractMoments{N}

A representation of statistical moments of a distribution

The following functions are supported

  • n_moments(m): get the number of recorded moments

The following getters return a single moment or throw an error if the moment has not been recorded (>N)

  • mean(m): get the first momemnt, i.e. the mean
  • var(m): get the second moment, i.e. the variance
  • skewness(m): get the third moment, i.e. the skewness
  • kurtosis(m): get the fourth moment, i.e. the kurtosis
  • getindex(m,i): get the ith moment, i.e. indexing m[i]

The basic implementation Moments is immutable and convert(AbstractArray, m::Moments) returns an SArray{N,T}.

Examples

m = Moments(1,0.2);
 n_moments(m) == 2
-var(m) == m[2]
kurtosis(m) # throws error because its above 2nd moment
source
DistributionFits.moments — Function
moments(D, ::Val{N} = Val(2))

Get the first N moments of a distribution.

Procudes an object of type AbstractMoments.

Examples

moments(LogNormal(), Val(4))  # first four moments 
-moments(Normal())  # mean and variance
source

QuantilePoint

The concept of a pair (p,q), i.e. a probability in [0,1] and associated quantile is captured by its own type. This allows dispatching the fit method.

DistributionFits.QuantilePoint — Type
QuantilePoint

A representation of a pair (p,q), i.e. (percentile,quantile).

Notes

Several macros help to construct QuantilePoints

  • @qp(q,p) quantile at specified p: QuantilePoint(q,p)

For Float64-based percentiles there are shortcuts

  • @qp_ll(q0_025) quantile at very low p: QuantilePoint(q0_025,0.025)
  • @qp_l(q0_05) quantile at low p: QuantilePoint(q0_05,0.05)
  • @qp_m(median) quantile at median: QuantilePoint(median,0.5)
  • @qp_u(q0_95) quantile at high p: QuantilePoint(q0_95,0.95)
  • @qp_uu(q0_975) quantile at very high p: QuantilePoint(q0_975,0.975)

For constructing QuantilePoints with type of percentiles other than Float64, use the corresponding functions, that create a percentiles of the type of given quantile. E.g. for a Float32-based QuantilePoint at very low percentile

  • qp_ll(0.2f0) constructs a QuantilePoint(0.2f0,0.025f0)

There are macros/functions for some commonly used sets of QuantilePoints: 90% and 95% confidence intervals:

  • @qs_cf90(q0_05,q0_95)
  • @qs_cf95(q0_025,q0_975) -> Set([QuantilePoint(q0_025,0.025),QuantilePoint(q0_975,0.975)]))
source
+var(m) == m[2]
kurtosis(m) # throws error because its above 2nd moment
source
DistributionFits.moments — Function
moments(D, ::Val{N} = Val(2))

Get the first N moments of a distribution.

Procudes an object of type AbstractMoments.

Examples

moments(LogNormal(), Val(4))  # first four moments 
+moments(Normal())  # mean and variance
source

QuantilePoint

The concept of a pair (p,q), i.e. a probability in [0,1] and associated quantile is captured by its own type. This allows dispatching the fit method.

DistributionFits.QuantilePoint — Type
QuantilePoint

A representation of a pair (p,q), i.e. (percentile,quantile).

Notes

Several macros help to construct QuantilePoints

  • @qp(q,p) quantile at specified p: QuantilePoint(q,p)

For Float64-based percentiles there are shortcuts

  • @qp_ll(q0_025) quantile at very low p: QuantilePoint(q0_025,0.025)
  • @qp_l(q0_05) quantile at low p: QuantilePoint(q0_05,0.05)
  • @qp_m(median) quantile at median: QuantilePoint(median,0.5)
  • @qp_u(q0_95) quantile at high p: QuantilePoint(q0_95,0.95)
  • @qp_uu(q0_975) quantile at very high p: QuantilePoint(q0_975,0.975)

For constructing QuantilePoints with type of percentiles other than Float64, use the corresponding functions, that create a percentiles of the type of given quantile. E.g. for a Float32-based QuantilePoint at very low percentile

  • qp_ll(0.2f0) constructs a QuantilePoint(0.2f0,0.025f0)

There are macros/functions for some commonly used sets of QuantilePoints: 90% and 95% confidence intervals:

  • @qs_cf90(q0_05,q0_95)
  • @qs_cf95(q0_025,q0_975) -> Set([QuantilePoint(q0_025,0.025),QuantilePoint(q0_975,0.975)]))
source
diff --git a/dev/gamma/index.html b/dev/gamma/index.html index f4ec152..d357425 100644 --- a/dev/gamma/index.html +++ b/dev/gamma/index.html @@ -1,3 +1,3 @@ Gamma · DistributionFits.jl
GitHub

Gamma distribution

The Gamma distribution has a scale and a shape parameter. It can be fitted using two quantiles.

d = fit(Gamma, @qp_m(0.5), @qp_uu(5));
-median(d) ≈ 0.5 && quantile(d, 0.975) ≈ 5

Fitting by mean or mode is not yet implemented.

+median(d) ≈ 0.5 && quantile(d, 0.975) ≈ 5

Fitting by mean or mode is not yet implemented.

diff --git a/dev/index.html b/dev/index.html index 7a0d34f..84db992 100644 --- a/dev/index.html +++ b/dev/index.html @@ -10,13 +10,13 @@ (mean(d), var(d)) .≈ (3.2,4.6)
d = fit(LogNormal, moments(Normal(3,1.2)));
 (mean(d), std(d)) .≈ (3,1.2)
# using StatsPlots
 plot(d, label = "lognormal", ylab="probability density")
-plot!(Normal(3,1.2), label = "normal")
source

Fit to several quantile points

StatsAPI.fit — Method
fit(D, lower::QuantilePoint, upper::QuantilePoint)

Fit a statistical distribution to a set of quantiles

Arguments

  • D: The type of the distribution to fit
  • lower: lower QuantilePoint (p,q)
  • upper: upper QuantilePoint (p,q)

Examples

d = fit(LogNormal, @qp_m(3), @qp_uu(5));
-quantile.(d, [0.5, 0.975]) ≈ [3,5]
source

Fit to mean, mode, median and a quantile point

StatsAPI.fit — Method
fit(D, val, qp, ::Val{stats} = Val(:mean))

Fit a statistical distribution to a quantile and given statistics

Arguments

  • D: The type of distribution to fit
  • val: The value of statistics
  • qp: QuantilePoint(q,p)
  • stats Which statistics to fit: defaults to Val(:mean). Alternatives are: Val(:mode), Val(:median)

Examples

d = fit(LogNormal, 5.0, @qp_uu(14));
+plot!(Normal(3,1.2), label = "normal")
source

Fit to several quantile points

StatsAPI.fit — Method
fit(D, lower::QuantilePoint, upper::QuantilePoint)

Fit a statistical distribution to a set of quantiles

Arguments

  • D: The type of the distribution to fit
  • lower: lower QuantilePoint (p,q)
  • upper: upper QuantilePoint (p,q)

Examples

d = fit(LogNormal, @qp_m(3), @qp_uu(5));
+quantile.(d, [0.5, 0.975]) ≈ [3,5]
source

Fit to mean, mode, median and a quantile point

StatsAPI.fit — Method
fit(D, val, qp, ::Val{stats} = Val(:mean))

Fit a statistical distribution to a quantile and given statistics

Arguments

  • D: The type of distribution to fit
  • val: The value of statistics
  • qp: QuantilePoint(q,p)
  • stats Which statistics to fit: defaults to Val(:mean). Alternatives are: Val(:mode), Val(:median)

Examples

d = fit(LogNormal, 5.0, @qp_uu(14));
 (mean(d),quantile(d, 0.975)) .≈ (5,14)
d = fit(LogNormal, 5.0, @qp_uu(14), Val(:mode));
-(mode(d),quantile(d, 0.975)) .≈ (5,14)
source

Currently supported distributions

Univariate continuous

Implementing support for another distribution

In order to use the fitting framework for a distribution MyDist, one needs to implement the following four methods.

fit(::Type{MyDist}, m::AbstractMoments)
+(mode(d),quantile(d, 0.975)) .≈ (5,14)
source

Currently supported distributions

Univariate continuous

Implementing support for another distribution

In order to use the fitting framework for a distribution MyDist, one needs to implement the following four methods.

fit(::Type{MyDist}, m::AbstractMoments)
 
 fit_mean_quantile(::Type{MyDist}, mean, qp::QuantilePoint)
 
 fit_mode_quantile(::Type{MyDist}, mode, qp::QuantilePoint)
 
-fit(::Type{MyDist}, lower::QuantilePoint, upper::QuantilePoint)

The default method for fit with stats = :median already works based on the methods for two quantile points. If the general method on two quantile points cannot be specified, one can alternatively implement method:

fit_median_quantile(::Type{MyDist}, median, qp::QuantilePoint)
+fit(::Type{MyDist}, lower::QuantilePoint, upper::QuantilePoint)

The default method for fit with stats = :median already works based on the methods for two quantile points. If the general method on two quantile points cannot be specified, one can alternatively implement method:

fit_median_quantile(::Type{MyDist}, median, qp::QuantilePoint)
diff --git a/dev/logitnormal/87f7c327.svg b/dev/logitnormal/f2283b31.svg similarity index 86% rename from dev/logitnormal/87f7c327.svg rename to dev/logitnormal/f2283b31.svg index c10ed17..4965783 100644 --- a/dev/logitnormal/87f7c327.svg +++ b/dev/logitnormal/f2283b31.svg @@ -1,50 +1,50 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/logitnormal/index.html b/dev/logitnormal/index.html index 1a4dc74..003f95f 100644 --- a/dev/logitnormal/index.html +++ b/dev/logitnormal/index.html @@ -3,4 +3,4 @@ mean(d), var(d) mode(d) ≈ 0.8

Specifying a logitnormal distribution by mode and peakedness

It is sometimes difficult to specify a precise upper quantile, because the logitnormal distribution is already constrained in (0,1). However, user might have an idea of the spread, or the inverse: peakedness, of the distribution.

With increasing spread, the logitnormal distribution becomes bimodal. The following functiion estimates the most spread, i.e most flat distribution that has a single mode at the given location.

DistributionFits.fit_mode_flat — Function
fit_mode_flat(::Type{LogitNormal}, mode::T; peakedness = 1.0)

Find the maximum-spread logitnormal distribution that has a single mode at given location.

More peaked distributions with given single mode can be optained by increasing argument peakedness. They will have a spread by originally inferred σ² devidied by peakedness.

Examples

m = 0.6
 d = fit_mode_flat(LogitNormal, m; peakedness = 1.5)
-mode(d) ≈ m
source

The found maximum spread parameter, σ, is devided by the peakedness argument to specify distributions given the mode that are more peaked.

Example block output

A shifted and scaled version of this distribution can be used as a moother alternative to the Bounded uniform distribution.

DistributionFits.shifloNormal — Function
shifloNormal(lower,upper)

Get a Shifted Flat LogitNormal distribution that is most spread with an extent between lower and upper. This is a more smooth alternative to the bounded uniform distribution.

source
+mode(d) ≈ msource

The found maximum spread parameter, σ, is devided by the peakedness argument to specify distributions given the mode that are more peaked.

Example block output

A shifted and scaled version of this distribution can be used as a moother alternative to the Bounded uniform distribution.

DistributionFits.shifloNormal — Function
shifloNormal(lower,upper)

Get a Shifted Flat LogitNormal distribution that is most spread with an extent between lower and upper. This is a more smooth alternative to the bounded uniform distribution.

source
diff --git a/dev/lognormal/index.html b/dev/lognormal/index.html index dada235..de0909b 100644 --- a/dev/lognormal/index.html +++ b/dev/lognormal/index.html @@ -2,7 +2,7 @@ LogNormal · DistributionFits.jl
GitHub

LogNormal distribution

The LogNormal distribution can be characterized by the exponent of its parameters:

  • exp(μ): the median
  • exp(σ): the multiplicative standard deviation $\sigma^*$.

Function σstar returns the multiplicative standard deviation.

A distribution can be specified by taking the log of median and $\sigma^*$

d = LogNormal(log(2), log(1.2))
 σstar(d) == 1.2

Alternatively the distribution can be specified by its mean and $\sigma^*$ using type AbstractΣstar

d = fit(LogNormal, 2, Σstar(1.2))
 (mean(d), σstar(d)) == (2, 1.2)

Detailed API

DistributionFits.σstar — Method
σstar(d)

Get the multiplicative standard deviation of LogNormal distribution d.

Arguments

  • d: The type of distribution to fit

Examples

d = LogNormal(2,log(1.2))
-σstar(d) == 1.2
source
StatsAPI.fit — Method
fit(D, mean, σstar)

Fit a statistical distribution of type D to mean and multiplicative standard deviation.

Arguments

  • D: The type of distribution to fit
  • mean: The moments of the distribution
  • σstar::AbstractΣstar: The multiplicative standard deviation

See also σstar, AbstractΣstar.

Examples

d = fit(LogNormal, 2, Σstar(1.1));
-(mean(d), σstar(d)) == (2, 1.1)
source
DistributionFits.AbstractΣstar — Type
Σstar <: AbstractΣstar

Represent the multiplicative standard deviation of a LogNormal distribution.

Supports dispatch of fit. Invoking the type as a function returns its single value.

Examples

a = Σstar(4.2)
-a() == 4.2
source
DistributionFits.fit_mean_relerror — Function
fit_mean_relerror(D, mean, relerror)

Fit a distribution of type D to mean and relative error.

Arguments

  • D: The type of distribution to fit
  • mean: The first moment of the distribution
  • relerror: The relative error, i.e. the coefficient of variation

Examples

d = fit_mean_relerror(LogNormal, 10.0, 0.03);
-(mean(d), std(d)/mean(d)) .≈ (10.0, 0.03)
source
+σstar(d) == 1.2source
StatsAPI.fit — Method
fit(D, mean, σstar)

Fit a statistical distribution of type D to mean and multiplicative standard deviation.

Arguments

  • D: The type of distribution to fit
  • mean: The moments of the distribution
  • σstar::AbstractΣstar: The multiplicative standard deviation

See also σstar, AbstractΣstar.

Examples

d = fit(LogNormal, 2, Σstar(1.1));
+(mean(d), σstar(d)) == (2, 1.1)
source
DistributionFits.AbstractΣstar — Type
Σstar <: AbstractΣstar

Represent the multiplicative standard deviation of a LogNormal distribution.

Supports dispatch of fit. Invoking the type as a function returns its single value.

Examples

a = Σstar(4.2)
+a() == 4.2
source
DistributionFits.fit_mean_relerror — Function
fit_mean_relerror(D, mean, relerror)

Fit a distribution of type D to mean and relative error.

Arguments

  • D: The type of distribution to fit
  • mean: The first moment of the distribution
  • relerror: The relative error, i.e. the coefficient of variation

Examples

d = fit_mean_relerror(LogNormal, 10.0, 0.03);
+(mean(d), std(d)/mean(d)) .≈ (10.0, 0.03)
source
diff --git a/dev/partype/index.html b/dev/partype/index.html index 328317e..42ddbdb 100644 --- a/dev/partype/index.html +++ b/dev/partype/index.html @@ -4,4 +4,4 @@ partype(d) == Float64

Parameter type, however, can be inferred from provided moments, mean, and mode.

d = fit(Exponential, Moments(3f0))  #f0 indicates Float32 literals
 partype(d) == Float32
d = fit(LogNormal, 3f0, @qp_uu(8))
 partype(d) == Float32
d = fit(LogNormal, 3f0, @qp_uu(8), Val(:mode))
-partype(d) == Float32
+partype(d) == Float32 diff --git a/dev/set_optimize/index.html b/dev/set_optimize/index.html index 9a1363b..8b06d0e 100644 --- a/dev/set_optimize/index.html +++ b/dev/set_optimize/index.html @@ -1,4 +1,4 @@ Dependencies · DistributionFits.jl
GitHub

Setting the optimize configuration

DistributionFits.AbstractDistributionFitOptimizer — Type
AbstractDistributionFitOptimizer
 OptimOptimizer <: AbstractDistributionFitOptimizer
-set_optimizer(::AbstractDistributionFitOptimizer)

DistributionFits.jl uses the following interface to opimize an univariate function f on bounded interval [lower,upper]:

optimize(f, ::AbstractDistributionFitOptimizer, lower, upper)

Returning an object with fields minimizer and converged.

DistributionFits.set_optimizer(::AbstractDistributionFitOptimizer) sets the specific AbstractDistributionFitOptimizer that is used throughout the package for calling the optimize function. Specializing this function with a concrete type, allows using different optimization packages.

By default, when the Optim.jl package is in scope, the OptimOptimizer is set, which implements the interface by using Optim's optimize function.

Hence, the module using DistributionFits.jl has to either

  • explicitly invoke using Optim, or
  • call set_optimizer with the concrete subtype of AbstractDistributionFitOptimizer for which the corresponding optimize method is implemented.

Developers implementing usage of a different specific optimizer see code in ext/DistributionFitsOptimExt.

source
+set_optimizer(::AbstractDistributionFitOptimizer)

DistributionFits.jl uses the following interface to opimize an univariate function f on bounded interval [lower,upper]:

optimize(f, ::AbstractDistributionFitOptimizer, lower, upper)

Returning an object with fields minimizer and converged.

DistributionFits.set_optimizer(::AbstractDistributionFitOptimizer) sets the specific AbstractDistributionFitOptimizer that is used throughout the package for calling the optimize function. Specializing this function with a concrete type, allows using different optimization packages.

By default, when the Optim.jl package is in scope, the OptimOptimizer is set, which implements the interface by using Optim's optimize function.

Hence, the module using DistributionFits.jl has to either

  • explicitly invoke using Optim, or
  • call set_optimizer with the concrete subtype of AbstractDistributionFitOptimizer for which the corresponding optimize method is implemented.

Developers implementing usage of a different specific optimizer see code in ext/DistributionFitsOptimExt.

source diff --git a/dev/weibull/index.html b/dev/weibull/index.html index 5afd4aa..72d03f7 100644 --- a/dev/weibull/index.html +++ b/dev/weibull/index.html @@ -1,3 +1,3 @@ Weibull · DistributionFits.jl
GitHub

Weibull distribution

The Weibull distribution has a scale and a shape parameter. It can be fitted using two quantiles.

d = fit(Weibull, @qp_m(0.5), @qp_uu(5));
-median(d) == 0.5 && quantile(d, 0.975) ≈ 5

Fitting by mean or mode is not yet implemented.

+median(d) == 0.5 && quantile(d, 0.975) ≈ 5

Fitting by mean or mode is not yet implemented.

diff --git a/dev/z_autodocs/index.html b/dev/z_autodocs/index.html index a8d9172..641ff36 100644 --- a/dev/z_autodocs/index.html +++ b/dev/z_autodocs/index.html @@ -1,8 +1,8 @@ DistributionFits · DistributionFits.jl
GitHub

DistributionFits

Documentation for DistributionFits.

[comment]: # (```@autodocs)

[comment]: # (Modules = [DistributionFits])

[comment]: # (```)

taken care of in index.md called only internally from fit, documented in docstring via ","

DistributionFits.fit_median_quantile — Function
fit(D, val, qp, ::Val{stats} = Val(:mean))

Fit a statistical distribution to a quantile and given statistics

Arguments

  • D: The type of distribution to fit
  • val: The value of statistics
  • qp: QuantilePoint(q,p)
  • stats Which statistics to fit: defaults to Val(:mean). Alternatives are: Val(:mode), Val(:median)

Examples

d = fit(LogNormal, 5.0, @qp_uu(14));
 (mean(d),quantile(d, 0.975)) .≈ (5,14)
d = fit(LogNormal, 5.0, @qp_uu(14), Val(:mode));
-(mode(d),quantile(d, 0.975)) .≈ (5,14)
source
DistributionFits.fit_mean_quantile — Function
fit(D, val, qp, ::Val{stats} = Val(:mean))

Fit a statistical distribution to a quantile and given statistics

Arguments

  • D: The type of distribution to fit
  • val: The value of statistics
  • qp: QuantilePoint(q,p)
  • stats Which statistics to fit: defaults to Val(:mean). Alternatives are: Val(:mode), Val(:median)

Examples

d = fit(LogNormal, 5.0, @qp_uu(14));
+(mode(d),quantile(d, 0.975)) .≈ (5,14)
source
DistributionFits.fit_mean_quantile — Function
fit(D, val, qp, ::Val{stats} = Val(:mean))

Fit a statistical distribution to a quantile and given statistics

Arguments

  • D: The type of distribution to fit
  • val: The value of statistics
  • qp: QuantilePoint(q,p)
  • stats Which statistics to fit: defaults to Val(:mean). Alternatives are: Val(:mode), Val(:median)

Examples

d = fit(LogNormal, 5.0, @qp_uu(14));
 (mean(d),quantile(d, 0.975)) .≈ (5,14)
d = fit(LogNormal, 5.0, @qp_uu(14), Val(:mode));
-(mode(d),quantile(d, 0.975)) .≈ (5,14)
source
DistributionFits.fit_mode_quantile — Function
fit(D, val, qp, ::Val{stats} = Val(:mean))

Fit a statistical distribution to a quantile and given statistics

Arguments

  • D: The type of distribution to fit
  • val: The value of statistics
  • qp: QuantilePoint(q,p)
  • stats Which statistics to fit: defaults to Val(:mean). Alternatives are: Val(:mode), Val(:median)

Examples

d = fit(LogNormal, 5.0, @qp_uu(14));
+(mode(d),quantile(d, 0.975)) .≈ (5,14)
source
DistributionFits.fit_mode_quantile — Function
fit(D, val, qp, ::Val{stats} = Val(:mean))

Fit a statistical distribution to a quantile and given statistics

Arguments

  • D: The type of distribution to fit
  • val: The value of statistics
  • qp: QuantilePoint(q,p)
  • stats Which statistics to fit: defaults to Val(:mean). Alternatives are: Val(:mode), Val(:median)

Examples

d = fit(LogNormal, 5.0, @qp_uu(14));
 (mean(d),quantile(d, 0.975)) .≈ (5,14)
d = fit(LogNormal, 5.0, @qp_uu(14), Val(:mode));
-(mode(d),quantile(d, 0.975)) .≈ (5,14)
source

internals

[comment]: # (fit(Type{LogNormal}, Any, AbstractΣstar))

+(mode(d),quantile(d, 0.975)) .≈ (5,14)source

internals

[comment]: # (fit(Type{LogNormal}, Any, AbstractΣstar))