BoxCox.BoxCoxTransformationType
BoxCoxTransformation <: PowerTransformation

Fields

  • λ: The transformation parameter

  • y: The original response, normalized by its geometric mean

  • X: A model matrix for the conditional distribution or Nothing for the unconditional distribution

  • atol: Tolerance for comparing λ to zero. Default is 1e-8

Note

All fields are considered internal and implementation details and may change at any time without being considered breaking.

Tips

  • To extract the λ parameter, use params.
  • The transformation is callable, meaning that you can do
bc = fit(BoxCoxTransformation, y)
y_transformed = bc.(y)
  • You can reduce the size of a BoxCoxTransformation in memory by using empty!, but certain diagnostics (e.g. plotting and computation of the loglikelihood will no longer be available).

See also boxcoxplot, params, boxcox.

Base.empty!Method
empty!(bt::BoxCoxTransformation)

Empty internal storage of bt.

For transformations fit to a large amount of data, this can reduce the size in memory. However, it means that loglikelihood, boxcoxplot and other functionality dependent on having access to the original data will no longer work.

After emptying, bt can still be used to transform new data.

Base.isapproxMethod
Base.isapprox(x::BoxCoxTransformation, y::BoxCoxTransformation; kwargs...)

Compare the λ parameter of x and y for approximate equality.

kwargs are passed on to isapprox for the parameters.

Note

Other internal structures of BoxCoxTransformation are not compared.

BoxCox._boxcox!Method
_boxcox!(y_trans, y, λ; kwargs...)

Internal method to compute boxcox at each element of y and store the result in y_trans.

BoxCox.boxcoxMethod
boxcox(λ; atol=0)
boxcox(λ, x; atol=0)

Compute the Box-Cox transformation of x for the parameter value λ.

The Box-Cox transformation is defined as:

\[\begin{cases} \frac{x^{\lambda} - 1}{\lambda} &\quad \lambda \neq 0 \\ \log x &\quad \lambda = 0 \end{cases}\]

for positive $x$. (If $x <= 0$, then $x$ must first be translated to be strictly positive.)

atol controls the absolute tolerance for treating λ as zero.

The one argument variant curries and creates a one-argument function of x for the given λ.

See also BoxCoxTransformation.

References

Box, George E. P.; Cox, D. R. (1964). "An analysis of transformations". Journal of the Royal Statistical Society, Series B. 26 (2): 211–252.

BoxCox.boxcoxplot!Method
boxcoxplot(bc::BoxCoxTransformation; kwargs...)
boxcoxplot!(axis, bc::BoxCoxTransformation; λ=nothing, n_steps=21)

Create a diagnostic plot for the Box-Cox transformation.

If λ is nothing, the range of possible values for the λ parameter is automatically determined, with a total of n_steps. If λ is a vector of numbers, then the λ parameter is evaluated at each element of that vector.

Note

You must load an appropriate Makie backend (e.g., CairoMakie or GLMakie) to actually render a plot.

Note

A meaningful plot is only possible when bc has not been empty!'ed.

Julia 1.6

The plotting functionality is defined unconditionally.

Julia 1.9

The plotting functionality interface is defined as a package extension and only loaded when Makie is available.

BoxCox.boxcoxplotMethod
boxcoxplot(bc::BoxCoxTransformation; kwargs...)
boxcoxplot!(axis, bc::BoxCoxTransformation; λ=nothing, n_steps=21)

Create a diagnostic plot for the Box-Cox transformation.

If λ is nothing, the range of possible values for the λ parameter is automatically determined, with a total of n_steps. If λ is a vector of numbers, then the λ parameter is evaluated at each element of that vector.

Note

You must load an appropriate Makie backend (e.g., CairoMakie or GLMakie) to actually render a plot.

Note

A meaningful plot is only possible when bc has not been empty!'ed.

Julia 1.6

The plotting functionality is defined unconditionally.

Julia 1.9

The plotting functionality interface is defined as a package extension and only loaded when Makie is available.

StatsAPI.confintMethod
StatsAPI.confint(bc::BoxCoxTransformation; level::Real=0.95, fast::Bool=nobs(bc) > 10_000)

Compute confidence intervals for λ, with confidence level level (by default 95%).

If fast, then a symmetric confidence interval around ̂λ is assumed and the upper bound is computed using the difference between the lower bound and λ. Symmetry is generally a safe assumption for approximate values and halves computation time.

If not fast, then the lower and upper bounds are computed separately.

StatsAPI.fitMethod
StatsAPI.fit(::Type{BoxCoxTransformation}, y::AbstractVector{<:Number}; atol=1e-8,
             algorithm::Symbol=:LN_BOBYQA, opt_atol=1e-8, opt_rtol=1e-8,
            maxiter=-1)
StatsAPI.fit(::Type{BoxCoxTransformation}, X::AbstractMatrix{<:Number},
             y::AbstractVector{<:Number}; atol=1e-8,
             algorithm::Symbol=:LN_BOBYQA, opt_atol=1e-8, opt_rtol=1e-8,
             maxiter=-1)
StatsAPI.fit(::Type{BoxCoxTransformation}, formula::FormulaTerm, data;
             atol=1e-8,
             algorithm::Symbol=:LN_BOBYQA, opt_atol=1e-8, opt_rtol=1e-8,
             maxiter=-1)
StatsAPI.fit(::Type{BoxCoxTransformation}, model::LinearMixedModel;
             atol=1e-8, progress=true,
             algorithm::Symbol=:LN_BOBYQA, opt_atol=1e-8, opt_rtol=1e-8,
             maxiter=-1)

Find the optimal λ value for a Box-Cox transformation of the data.

When no X is provided, y is treated as an unconditional distribution.

When X is provided, y is treated as distribution conditional on the linear predictor defined by X. At each iteration step, a simple linear regression is fit to the transformed y with X as the model matrix.

If a FormulaTerm is provided, then X is constructed using that specification and data.

If a LinearMixedModel is provided, then X and y are extracted from the model object.

Note

The formula interface is only available if StatsModels.jl is loaded either directly or via another package such GLM.jl or MixedModels.jl.

Julia 1.6
  • The formula interface is defined unconditionally, but @formula is not loaded.
  • The MixedModels interface is defined unconditionally.
Julia 1.9
  • The formula interface is defined as a package extension.
  • The MixedModels interface is defined as a package extension.

atol controls the absolute tolerance for treating λ as zero.

The opt_ keyword arguments are tolerances passed onto NLopt.

maxiter specifies the maximum number of iterations to use in optimization; negative values place no restrictions.

algorithm is a valid NLopt algorithm to use in optimization.

progress enables progress bars for intermediate model fits during the optimization process.

StatsAPI.paramsMethod
StatsAPI.params(bc::BoxCoxTransformation)

Return a vector of all parameters, i.e. [λ].