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

See also boxcoxplot, params, boxcox.

source
BoxCox.YeoJohnsonTransformationType
YeoJohnsonTransformation <: PowerTransformation

Fields

  • λ: The transformation parameter

  • y: The original response

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

  • atol: Tolerance for comparing λ to zero or two. 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
yj = fit(YeoJohnsonTransformation, y)
y_transformed = yj.(y)
  • You can reduce the size of a YeoJohnsonTransformation in memory by using empty!, but certain diagnostics (e.g. plotting and computation of the loglikelihood will no longer be available).
source
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.

source
BoxCox.boxcoxplot!Method
boxcoxplot(bc::PowerTransformation; kwargs...)
boxcoxplot!(axis::Axis, bc::PowerTransformation;
            λ=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.

source
BoxCox.boxcoxplotMethod
boxcoxplot(bc::PowerTransformation; kwargs...)
boxcoxplot!(axis::Axis, bc::PowerTransformation;
            λ=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.

source
BoxCox.yeojohnsonMethod
yeojohnson(λ; atol=0)
yeojohnson(λ, x; atol=0)

\[\begin{cases} ((x_i+1)^\lambda-1)/\lambda & \text{if }\lambda \neq 0, y \geq 0 \\ \log(y_i + 1) & \text{if }\lambda = 0, y \geq 0 \\ -((-x_i + 1)^{(2-\lambda)} - 1) / (2 - \lambda) & \text{if }\lambda \neq 2, y < 0 \\ -\log(-x_i + 1) & \text{if }\lambda = 2, y < 0 \end{cases}\]

atol controls the absolute tolerance for treating λ as zero or two.

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

See also YeoJohnsonTransformation.

References

Yeo, I.-K., & Johnson, R. A. (2000). A new family of power transformations to improve normality or symmetry. Biometrika, 87(4), 954–959. https://doi.org/10.1093/biomet/87.4.954

source
StatsAPI.confintMethod
StatsAPI.confint(x::PowerTransformation; 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.

source
StatsAPI.fitMethod
StatsAPI.fit(::Type{<:PowerTransformation}, y::AbstractVector{<:Number}; atol=1e-8,
             algorithm::Symbol=:LN_BOBYQA, opt_atol=1e-8, opt_rtol=1e-8,
            maxiter=-1)
StatsAPI.fit(::Type{<:PowerTransformation}, 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{<:PowerTransformation}, formula::FormulaTerm, data;
             atol=1e-8,
             algorithm::Symbol=:LN_BOBYQA, opt_atol=1e-8, opt_rtol=1e-8,
             maxiter=-1)
StatsAPI.fit(::Type{<:PowerTransformation}, 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 power 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.

source
StatsAPI.paramsMethod
StatsAPI.params(x::PowerTransformation)

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

source