transforms

Stateful transform classes (center, norm, zscore, scale) for formula evaluation.

Attributes:

Classes:

Functions:

Attributes¶

STATEFUL_TRANSFORMS¶

STATEFUL_TRANSFORMS: dict[str, type[StatefulTransform]] = {'center': Center, 'norm': Norm, 'zscore': Zscore, 'scale': Scale, 'rank': Rank, 'signed_rank': SignedRank}

Classes¶

Center¶

Bases: StatefulTransform

Mean-centering transform: x - mean(x).

Subtracts the mean computed from training data.

Note: This class is intentionally mutable (see StatefulTransform).

Examples:

>>> transform = Center()
>>> train = np.array([10.0, 20.0, 30.0])
>>> transform.fit_transform(train)  # mean=20
array([-10.,   0.,  10.])
>>> new = np.array([25.0, 35.0])
>>> transform.transform(new)  # uses mean=20 from training
array([ 5., 15.])

Functions:

Attributes:

Attributes¶

fitted¶

fitted: bool

Whether transform has been fitted to data.

name¶

name = 'center'

state¶

state: TransformState

Get current transform state.

Functions¶

fit¶

fit(x: NDArray[np.floating[Any]]) -> None

Compute mean from training data.

fit_transform¶

fit_transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Fit to data and transform in one step.

Parameters:

Returns:

transform¶

transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Subtract training mean from data.

Norm¶

Bases: StatefulTransform

Normalization transform: x / std(x).

Divides by the standard deviation computed from training data. Does NOT subtract the mean (use Zscore or Scale for centered transforms).

Note: This class is intentionally mutable (see StatefulTransform).

Examples:

>>> transform = Norm()
>>> train = np.array([0.0, 10.0, 20.0])
>>> transform.fit_transform(train)  # std=10
array([0., 1., 2.])
>>> new = np.array([5.0, 15.0])
>>> transform.transform(new)  # uses std=10 from training
array([0.5, 1.5])

Functions:

Attributes:

Attributes¶

fitted¶

fitted: bool

Whether transform has been fitted to data.

name¶

name = 'norm'

state¶

state: TransformState

Get current transform state.

Functions¶

fit¶

fit(x: NDArray[np.floating[Any]]) -> None

Compute std from training data.

fit_transform¶

fit_transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Fit to data and transform in one step.

Parameters:

Returns:

transform¶

transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Divide data by training std.

Rank¶

Bases: StatefulTransform

Average-method rank transform: rank(x).

Converts values to their ranks using the average method for ties, matching R’s default rank() behaviour.

On training data (fit_transform), computes exact average-method ranks. On new data (transform), interpolates ranks using the training distribution for smooth out-of-sample predictions.

Note: This class is intentionally mutable (see StatefulTransform).

Examples:

>>> transform = Rank()
>>> train = np.array([10.0, 30.0, 20.0])
>>> transform.fit_transform(train)
array([1., 3., 2.])
>>> new = np.array([15.0, 35.0])
>>> transform.transform(new)  # interpolated ranks
array([1.5, 3. ])

Functions:

Attributes:

Attributes¶

fitted¶

fitted: bool

Whether transform has been fitted to data.

name¶

name = 'rank'

state¶

state: TransformState

Get current transform state.

Functions¶

fit¶

fit(x: NDArray[np.floating[Any]]) -> None

Store sorted training values for newdata interpolation.

Parameters:

fit_transform¶

fit_transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Compute exact average-method ranks for training data.

Overrides the default fit+transform because exact ranks on training data differ from the interpolation used for new data.

Parameters:

Returns:

transform¶

transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Interpolate ranks for new data using training distribution.

Parameters:

Returns:

Scale¶

Bases: StatefulTransform

Gelman scaling transform: (x - mean(x)) / (2 * std(x)).

Centers and divides by 2 standard deviations, following Gelman (2008). This makes continuous predictor coefficients directly comparable to binary predictor coefficients in regression models.

A 2-SD change roughly corresponds to moving from “low” to “high” in the predictor’s range, analogous to the full effect of a binary variable.

Note: This class is intentionally mutable (see StatefulTransform).

Gelman, A. (2008). Scaling regression inputs by dividing by two Gelman, A. (2008). Scaling regression inputs by dividing by two standard deviations. Statistics in Medicine, 27, 2865-2873.

Examples:

>>> transform = Scale()
>>> train = np.array([10.0, 20.0, 30.0])
>>> transform.fit_transform(train)  # mean=20, std=10
array([-0.5,  0. ,  0.5])
>>> new = np.array([25.0, 35.0])
>>> transform.transform(new)  # uses training mean/std
array([0.25, 0.75])

Functions:

Attributes:

Attributes¶

fitted¶

fitted: bool

Whether transform has been fitted to data.

name¶

name = 'scale'

state¶

state: TransformState

Get current transform state.

Functions¶

fit¶

fit(x: NDArray[np.floating[Any]]) -> None

Compute mean and std from training data.

fit_transform¶

fit_transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Fit to data and transform in one step.

Parameters:

Returns:

transform¶

transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Apply Gelman scaling using training mean and 2*std.

SignedRank¶

Bases: StatefulTransform

Signed-rank transform: sign(x) * rank(|x|).

Used for Wilcoxon signed-rank tests as linear models. Signs are preserved while absolute values are ranked.

On training data (fit_transform), computes exact signed ranks. On new data (transform), interpolates absolute-value ranks using the training distribution, then restores signs.

Note: This class is intentionally mutable (see StatefulTransform).

Examples:

>>> transform = SignedRank()
>>> train = np.array([-3.0, 1.0, 2.0])
>>> transform.fit_transform(train)
array([-3.,  1.,  2.])

Functions:

Attributes:

Attributes¶

fitted¶

fitted: bool

Whether transform has been fitted to data.

name¶

name = 'signed_rank'

state¶

state: TransformState

Get current transform state.

Functions¶

fit¶

fit(x: NDArray[np.floating[Any]]) -> None

Store sorted |x| training values for newdata interpolation.

Parameters:

fit_transform¶

fit_transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Compute exact signed ranks for training data.

Parameters:

Returns:

transform¶

transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Interpolate signed ranks for new data.

Parameters:

Returns:

StatefulTransform¶

StatefulTransform() -> None

Bases: ABC

Base class for stateful transforms.

Stateful transforms capture parameters from training data and reuse them when transforming new data for predictions.

Note: This class is intentionally mutable. The fit() method updates internal state (_params, _fitted) which is reused by transform().

Functions:

Attributes:

Attributes¶

fitted¶

fitted: bool

Whether transform has been fitted to data.

name¶

name: str = 'base'

state¶

state: TransformState

Get current transform state.

Functions¶

fit¶

fit(x: NDArray[np.floating[Any]]) -> None

Compute and store parameters from training data.

Parameters:

fit_transform¶

fit_transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Fit to data and transform in one step.

Parameters:

Returns:

transform¶

transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Transform data using stored parameters.

Parameters:

Returns:

TransformState¶

TransformState(name: str, params: dict[str, Any]) -> None

Container for captured transform parameters.

Attributes:

Attributes¶

name¶

name: str

params¶

params: dict[str, Any]

Zscore¶

Bases: StatefulTransform

Z-score transform: (x - mean(x)) / std(x).

Traditional standardization using mean and std from training data. Coefficients represent effect of 1 SD change.

Note: This class is intentionally mutable (see StatefulTransform).

Examples:

>>> transform = Zscore()
>>> train = np.array([10.0, 20.0, 30.0])
>>> transform.fit_transform(train)  # mean=20, std=10
array([-1.,  0.,  1.])
>>> new = np.array([25.0, 35.0])
>>> transform.transform(new)  # uses training mean/std
array([0.5, 1.5])

Functions:

Attributes:

Attributes¶

fitted¶

fitted: bool

Whether transform has been fitted to data.

name¶

name = 'zscore'

state¶

state: TransformState

Get current transform state.

Functions¶

fit¶

fit(x: NDArray[np.floating[Any]]) -> None

Compute mean and std from training data.

fit_transform¶

fit_transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Fit to data and transform in one step.

Parameters:

Returns:

transform¶

transform(x: NDArray[np.floating[Any]]) -> NDArray[np.floating[Any]]

Apply z-score using training mean and std.

Functions¶

build_transform¶

build_transform(name: str) -> StatefulTransform

Create a stateful transform instance by name.

Parameters:

Returns:

Examples:

>>> transform = build_transform("center")
>>> transform.fit_transform(np.array([1.0, 2.0, 3.0]))
array([-1.,  0.,  1.])