# API

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).

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 λ.

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::Axis, bc::BoxCoxTransformation;
λ=nothing, n_steps=21, xlabel="λ", ylabel="log likelihood",
conf_level=nothing, attributes...)

Create a diagnostic plot for the Box-Cox transformation.

The mutating method for Axis returns the (modified) original Axis. The non-mutating method returns a Figure.

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.

If conf_level is nothing, then no confidence interval is displayed.

attributes are forwarded to scatterlines!.

Note

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

Note

The plotting functionality interface is defined as a package extension and only loaded when Makie is available. You must load an appropriate Makie backend (e.g., CairoMakie or GLMakie) to actually render a plot.

BoxCox.boxcoxplotMethod
boxcoxplot(bc::BoxCoxTransformation; kwargs...)
boxcoxplot!(axis::Axis, bc::BoxCoxTransformation;
λ=nothing, n_steps=21, xlabel="λ", ylabel="log likelihood",
conf_level=nothing, attributes...)

Create a diagnostic plot for the Box-Cox transformation.

The mutating method for Axis returns the (modified) original Axis. The non-mutating method returns a Figure.

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.

If conf_level is nothing, then no confidence interval is displayed.

attributes are forwarded to scatterlines!.

Note

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

Note

The plotting functionality interface is defined as a package extension and only loaded when Makie is available. You must load an appropriate Makie backend (e.g., CairoMakie or GLMakie) to actually render a plot.

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.

Note
• 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. [λ].