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 |
1
|
knots
|
sequence of array-like
|
Explicit interior knots, one array per variable, in the units of the data. Overrides |
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 |
False
|
init
|
pca
|
Start from the PCA scores, plus |
"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 |
1e-6
|
max_iter
|
int
|
Maximum number of iterations; a :class: |
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 |
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 |
feature_names_in_ |
ndarray of str
|
Variable names, when |
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
|
Warns:
| Type | Description |
|---|---|
SmallSampleWarning
|
When n < 5 (degree + knots) for some variable. |
ConvergenceWarning
|
When |
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 |
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 |
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 |
1e-10
|
Returns:
| Type | Description |
|---|---|
ndarray of shape (n, rank)
|
Orthonormal columns spanning the column space of |