boxCoxTransform¶
Performs a forward or an inverse Box-Cox (power) transformation.
Synopsis¶
boxCoxTransform (z, power)
Required Arguments¶
- float
z[]
(Input) - Array of length
nObservations
containing the observations. - float
power
(Input) - Exponent parameter in the Box-Cox (power) transformation.
Return Value¶
An array of length nObservations
containing the transformed data. If no
value can be computed, then None
is returned.
Optional Arguments¶
shift
, float (Input)Shift parameter in the Box-Cox (power) transformation. Parameter shift must satisfy the relation min (z(i)) +
shift
> 0.Default:
shift
= 0.0.inverseTransform
(Input)- If
inverseTransform
is specified, the inverse transform is performed.
Description¶
Function boxCoxTransform
performs a forward or an inverse Box-Cox (power)
transformation of n = nObservations
observations \(\{Z_t\}\) for
\(t=1,2,\ldots,n\).
The forward transformation is useful in the analysis of linear models or models with nonnormal errors or nonconstant variance (Draper and Smith 1981, p. 222). In the time series setting, application of the appropriate transformation and subsequent differencing of a series can enable model identification and parameter estimation in the class of homogeneous stationary autoregressive-moving average models. The inverse transformation can later be applied to certain results of the analysis, such as forecasts and prediction limits of forecasts, in order to express the results in the scale of the original data. A brief note concerning the choice of transformations in the time series models is given in Box and Jenkins (1976, p. 328).
The class of power transformations discussed by Box and Cox (1964) is defined by
where \(Z_t+\xi>0\) for all t. Since
the family of power transformations is continuous.
Let λ = power
and ξ = shift
; then, the computational formula used by
boxCoxTransform
is given by
where \(Z_t+\xi>0\) for all t. The computational and Box-Cox formulas differ only in the scale and origin of the transformed data. Consequently, the general analysis of the data is unaffected (Draper and Smith 1981, p. 225).
The inverse transformation is computed by
where \(\{Z_t\}\) now represents the result computed by
boxCoxTransform
for a forward transformation of the original data using
parameters λ and ξ.
Examples¶
Example 1¶
The following example performs a Box-Cox transformation with power
= 2.0
on 10 data points.
from numpy import *
from pyimsl.stat.boxCoxTransform import boxCoxTransform
from pyimsl.stat.writeMatrix import writeMatrix
power = 2.0
z = (1.0, 2.0, 3.0, 4.0, 5.0, 5.5, 6.5, 7.5, 8.0, 10.0)
# Transform Data using Box Cox Transform
y = boxCoxTransform(z, power)
writeMatrix("Transformed Data", y, writeFormat="%5.1f")
Output¶
Transformed Data
1 2 3 4 5 6 7 8 9 10
1.0 4.0 9.0 16.0 25.0 30.2 42.2 56.2 64.0 100.0
Example 2¶
This example extends the first example—an inverse transformation is applied to the transformed data to return to the original data values.
from numpy import *
from pyimsl.stat.boxCoxTransform import boxCoxTransform
from pyimsl.stat.writeMatrix import writeMatrix
power = 2.0
z = (1.0, 2.0, 3.0, 4.0, 5.0, 5.5, 6.5, 7.5, 8.0, 10.0)
# Transform Data using Box Cox Transform
x = boxCoxTransform(z, power)
writeMatrix("Transformed Data", x, writeFormat="%5.1f")
# Perform an Inverse Transform on the Transformed Data
y = boxCoxTransform(x, power, inverseTransform=True)
writeMatrix("Inverse Transformed Data", y, writeFormat="%5.1f")
Output¶
Transformed Data
1 2 3 4 5 6 7 8 9 10
1.0 4.0 9.0 16.0 25.0 30.2 42.2 56.2 64.0 100.0
Inverse Transformed Data
1 2 3 4 5 6 7 8 9 10
1.0 2.0 3.0 4.0 5.0 5.5 6.5 7.5 8.0 10.0
Fatal Errors¶
IMSLS_ILLEGAL_SHIFT |
“shift ” = # and the smallest
element of “z ” is
“z [#]” = #. “shift ”
plus “z [#]” = #.
“shift ” + “z [i]”
must be greater than 0 for i =
1,…, “nObservations ”.
“nObservations ” = #. |
IMSLS_BCTR_CONTAINS_NAN |
One or more elements of “z ”
is equal to NaN (Not a number). No
missing values are allowed. The
smallest index of an element of
“z ” that is equal to NaN is
#. |
IMSLS_BCTR_F_UNDERFLOW |
Forward transform. “power ” =
#. “shift ” = #. The minimum
element of “z ” is
“z [#]” = #. (“z [#]”+
“shift ”) ^ “power ”
will underflow. |
IMSLS_BCTR_F_OVERFLOW |
Forward transformation.
“power ” = #. “shift ”
= #. The maximum element of
“z ” is “z [#]” = #.
(“z [#]” + “shift ”) ^
“power ” will overflow. |
IMSLS_BCTR_I_UNDERFLOW |
Inverse transformation.
“power ” = #. The minimum
element of “z ” is
“z [#]” = #.
exp(“z [#]”) will underflow. |
IMSLS_BCTR_I_OVERFLOW |
Inverse transformation.
“power ” = #. The maximum
element of “z [#]” = #.
exp(“z [#]”) will overflow. |
IMSLS_BCTR_I_ABS_UNDERFLOW |
Inverse transformation.
“power ” = #. The element of
“z ” with the smallest
absolute value is “z [#]” =
#. “z [#]” ^ (1/
“power ”) will underflow. |
IMSLS_BCTR_I_ABS_OVERFLOW |
Inverse transformation.
“power ” = #. The element of
“z ” with the largest
absolute value is “z [#]” =
#. “z [#]” ^ (1/
“power ”) will overflow. |