Skip to content

QLPCA and warnings

QLPCA

QLPCA(n_components=2, degree=1, n_knots=1, knots=None, monotone=False, init='pca', n_init=10, random_state=None, legacy=False, tol=1e-06, max_iter=1000)

Bases: ClassNamePrefixFeaturesOutMixin, TransformerMixin, BaseEstimator

Quasi-linear PCA: PCA with low-order spline transformations of the variables.

A scikit-learn transformer (fit, transform, fit_transform, inverse_transform, get_feature_names_out; works with clone, Pipeline and set_output). Each variable is transformed by a spline of degree degree with interior knots, and the transformations and the components are fitted jointly by alternating least squares (Lavado & Calapez 2011; Lavado 2012).

Parameters:

Name Type Description Default
n_components int

Number of retained components p.

2
degree int or sequence of int

Spline degree v, one value for all variables or one per variable (qlPCA proper uses 1).

1
n_knots int or sequence of int

Number of interior knots r, one value or one per variable. Knots are placed at the percentiles round(100 i / (r + 1)) (MATLAB prctile). degree=1, n_knots=0 is ordinary PCA.

1
knots sequence of array-like

Explicit interior knots, one array per variable, in the units of the data. Overrides n_knots. Ignored when legacy=True.

None
monotone bool

Restrict every f_j to be nondecreasing (I-splines with nonnegative coefficients and a free intercept). Decreasing relations then appear as negative loadings. Ignored when legacy=True.

False
init pca

Start from the PCA scores, plus n_init random orthonormal starts; the fit with the lowest loss is kept. Ignored when legacy=True.

"pca"
n_init int

Number of random starts in addition to the PCA start.

10
random_state (None, int, Generator or RandomState)

Seed for the random starts.

None
legacy bool

Reproduce the 2012 MATLAB behaviour (start from the first p columns of the standardised pseudo-indicator matrix, single start, eigen-decomposition update, unique values required).

False
tol float

Stop when the absolute change of the loss between iterations is below tol.

1e-6
max_iter int

Maximum number of iterations; a :class:ConvergenceWarning is issued when it is reached.

1000

Attributes:

Name Type Description
scores_ ndarray of shape (n_samples, n_components)

Object scores X (columns with norm sqrt(n)).

transformed_ ndarray of shape (n_samples, n_features)

Transformed variables F (centred, norm sqrt(n)).

loadings_ ndarray of shape (n_features, n_components)

Loadings A (correlations between the transformed variables and the components).

eigenvalues_ ndarray of shape (n_components,)

Largest eigenvalues of F'F / n.

all_eigenvalues_ ndarray of shape (n_features,)

All eigenvalues of F'F / n.

vaf_ ndarray of shape (n_components,)

Percentage of variance accounted for by each component.

communalities_ ndarray of shape (n_features,)

Communality of each variable (sum of its squared loadings).

loss_ float

Final loss of the retained fit.

loss_history_ ndarray

Loss at each iteration of the retained fit.

n_iter_ int

Number of iterations of the retained fit.

losses_ ndarray

Final loss of each start (the first is the PCA start).

knots_ list of ndarray

Full knot sequences, on the standardised scale of each variable.

coef_ list of ndarray

Spline coefficients of each variable: on the centred B-spline basis by default, on the I-spline basis if monotone=True, on the standardised I-spline columns if legacy=True.

mean_, std_ ndarray of shape (n_features,)

Means and standard deviations used to standardise the variables.

n_features_in_ int

Number of variables seen in fit.

feature_names_in_ ndarray of str

Variable names, when fit received a DataFrame.

Notes

Sign convention (DESIGN D6): each transformed variable is oriented so that corr(f_j, h_j) >= 0 and each component so that its loading of largest absolute value is positive. For V-shaped transformations the orientation of that variable is fragile: read it through the transformation plot.

Examples:

>>> from qlpca import QLPCA
>>> from qlpca.datasets import make_cylinder
>>> X, names = make_cylinder(n=51, random_state=0)
>>> model = QLPCA(n_components=2, n_knots=2, random_state=0).fit(X)
>>> model.scores_.shape
(51, 2)

fit

fit(X, y=None)

Fit the model to X.

Parameters:

Name Type Description Default
X array-like or DataFrame of shape (n_samples, n_features)

Continuous variables; complete data (no NaN or inf) and at least two observations.

required
y None

Ignored.

None

Returns:

Name Type Description
self QLPCA

The fitted estimator.

Raises:

Type Description
ValueError

For missing or infinite values, constant variables, fewer than two observations, an invalid n_components or (legacy=True) ties within a variable.

Warns:

Type Description
SmallSampleWarning

When n < 5 (degree + knots) for some variable.

ConvergenceWarning

When max_iter is reached.

fit_transform

fit_transform(X, y=None)

Fit the model and return the object scores of the training rows.

Parameters:

Name Type Description Default
X array-like or DataFrame of shape (n_samples, n_features)

Training data.

required
y None

Ignored.

None

Returns:

Type Description
ndarray of shape (n_samples, n_components)

The object scores scores_.

transform

transform(X)

Object scores of (new) rows; degree 1 only.

X_new = sqrt(n) F_new A (A'F'FA)^(-1/2) (DESIGN D10; equivalent to thesis eq. 3.5), which returns scores_ exactly for the training rows. F_new comes from :meth:transform_variables: values outside the training range are extrapolated linearly (DESIGN D11). Scores of new observations are reliable only inside the training range.

Parameters:

Name Type Description Default
X array-like or DataFrame of shape (n_samples, n_features)

Rows to project.

required

Returns:

Type Description
ndarray of shape (n_samples, n_components)

Object scores.

Warns:

Type Description
ExtrapolationWarning

When some rows fall outside the training range of some variable.

transform_variables

transform_variables(X)

Optimal transformations f_j of (new) rows; degree 1 only.

Inside the training range of variable j, f_j is the fitted piecewise-linear function; the training rows get exactly the columns of transformed_. Outside the training range f_j is extrapolated linearly from its first or last segment (DESIGN D11). Nothing in the data supports the transformation there: with heavy-tailed variables a single extreme value can dominate the result. Transform such variables beforehand (e.g. log) or do not project new data; qlPCA is a descriptive method.

Parameters:

Name Type Description Default
X array-like or DataFrame of shape (n_samples, n_features)

Rows to transform (same variables as in fit).

required

Returns:

Type Description
ndarray of shape (n_samples, n_features)

Transformed variables.

Warns:

Type Description
ExtrapolationWarning

When some rows fall outside the training range of some variable (number of rows and names of the variables in the message).

inverse_transform

inverse_transform(scores)

Reconstruct the data from object scores; degree 1 only.

F_hat = X A', then each f_j is inverted. The inverse of a piecewise-linear f_j is a function only where f_j is strictly monotone: where it is not unique the first segment whose range contains the value is used, and values outside the range of f_j are clipped. With monotone=True the fit often has flat segments (a coefficient exactly zero): all observations on a plateau are reconstructed at the knot where the plateau starts, although transform_variables of the reconstruction still returns F.

Parameters:

Name Type Description Default
scores array-like of shape (n_samples, n_components)

Object scores.

required

Returns:

Type Description
ndarray of shape (n_samples, n_features)

Reconstructed data in the original units.

variable_transformation

variable_transformation(j, n_points=200)

Curve of the optimal transformation of one variable over its training range (any degree).

Parameters:

Name Type Description Default
j int

Index of the variable.

required
n_points int

Number of grid points.

200

Returns:

Name Type Description
x ndarray of shape (n_points,)

Grid in the original units of the variable.

f ndarray of shape (n_points,)

Values of f_j on the grid.

ConvergenceWarning

Bases: UserWarning

The loss change did not fall below tol within max_iter iterations.

SmallSampleWarning

Bases: UserWarning

Fewer than 5 w observations for a variable whose spline has w = degree + knots parameters.

The thesis recommends n >= 5 w; below that the fit is likely to be over-parametrised.

ExtrapolationWarning

Bases: UserWarning

New observations fall outside the training range of some variable.

Their transformations are extrapolated linearly from the last segment of f_j (DESIGN D11).

orthonormal_basis

orthonormal_basis(B, rtol=1e-10)

Orthonormal basis of the column span of the centred matrix B.

Parameters:

Name Type Description Default
B ndarray of shape (n, k)

Basis matrix (for example a B-spline design matrix).

required
rtol float

Singular values below rtol times the largest are treated as zero (rank-revealing).

1e-10

Returns:

Type Description
ndarray of shape (n, rank)

Orthonormal columns spanning the column space of B - B.mean(0).