qlPCA — quasi-linear principal components analysis
Documentation: https://nlavadodatasci.github.io/quasi-linear-PCA/ (user guide, API reference, thesis replication, comparisons).
This repository has two purposes:
- A Python quant package,
qlpca, for direct use in data analysis —from qlpca import QLPCA, thenfit/transform— implementing quasi-linear PCA (qlPCA).QLPCAis a scikit-learn transformer: it works withPipeline,clone,GridSearchCV,set_outputand pandas DataFrames (see Use with scikit-learn). - A chapter-by-chapter replication of the PhD thesis in which the method was proposed (Lavado, 2012), in notebooks that use the package.
qlPCA extends principal components analysis to nonlinear relations by transforming each continuous variable with a low-order spline — usually piecewise linear, with one to three interior knots — chosen jointly with the components by alternating least squares. Continuous variables enter directly, with no discretisation step.
What it gives the user. qlPCA reads as ordinary PCA with flexibility added knot by knot: with no interior
knots it is PCA, and each knot lets a variable's contribution change from one range of its values to the next.
That change is reported directly as piecewise loadings — the loading of each variable on each component,
segment by segment, on the original scale. The package starts from the PCA solution and adds random starts, keeping the
best and reporting the loss of each, which guards against local optima; it projects new observations and reconstructs data (degree 1); knots can
be placed at percentiles or at values that mean something in the application; and QLPCA works as a
scikit-learn transformer. On wind turbine SCADA data, knots placed at the turbine's control regions add 11 to 13
points of out-of-sample variance over linear PCA, in all six turbines of a wind farm — see the
Kelmarsh application. How qlPCA relates to princals (Gifi) is in
comparison/princals/.
The listings printed in the thesis are transcribed in
matlab_original/, and a literal numpy port of them is in
prototype/; the package in src/qlpca is tested against both.
Installation
Requires Python 3.10 or later.
pip install "git+https://github.com/nlavadodatasci/quasi-linear-PCA"
# or, to run the tests and notebooks from a clone:
git clone https://github.com/nlavadodatasci/quasi-linear-PCA
cd quasi-linear-PCA
pip install -e ".[dev,notebooks]"
Quick start
from qlpca import QLPCA
from qlpca.datasets import make_cylinder
X, names = make_cylinder(n=51, noise=0.10, random_state=0) # simulated "cylinder problem": 12 variables
model = QLPCA(n_components=2, degree=1, n_knots=2, random_state=0).fit(X)
print(model.eigenvalues_) # variance accounted for by each component
print(model.loadings_.shape) # nonlinear loadings, one row per variable
print(model.communalities_) # per-variable fit
print(model.transform(X[:3])) # project (new) observations on the components (degree 1)
print(model.inverse_transform(model.scores_).shape) # reconstruct data from object scores (degree 1)
The thesis chapter 4 data are shipped with the package: X, variables, countries = load_st_gender()
(see Data). QLPCA is a scikit-learn transformer: it accepts DataFrames (the column names are kept
in feature_names_in_ and used by the plots) and works in pipelines.
Diagnostics (qlpca.diagnostics: VAF, communalities, piecewise loadings) and plots
(qlpca.plots: scree plots, transformation plots, biplots) work on a fitted model.
Two modes
- Default — a modernised algorithm for new analyses: centred B-spline basis, PCA start plus random
starts (keeps the lowest loss), truncated-SVD updates, ties allowed, optional
monotone=True(non-decreasing transformations), knots per variable. legacy=True— the behaviour of the 2012 MATLAB code, used to compare with the thesis number by number.
The choices and the evidence behind them are in docs/DESIGN.md; the algorithm as
printed in the thesis, and how it differs from the MATLAB listings, in docs/SPEC.md.
The thesis pseudo-code omits one essential step — centring the spline basis (an intercept) — which the
MATLAB code performs; notebook 04 gives the corrected pseudo-code.
Use with scikit-learn
QLPCA is a scikit-learn transformer (BaseEstimator, TransformerMixin), tested with scikit-learn's
estimator checks. What works:
clone,get_params/set_params,Pipeline,GridSearchCV(inside a pipeline with a supervised step, or with your own scorer:QLPCAhas noscoremethod);set_output(transform="pandas"),get_feature_names_out()(qlpca0,qlpca1, ...);- pandas DataFrames as input: the column names are kept in
feature_names_in_, used in warnings and plots, and checked again bytransform.
from sklearn.pipeline import make_pipeline
from sklearn.linear_model import Ridge
pipe = make_pipeline(QLPCA(n_components=2, n_knots=2, random_state=0), Ridge())
Keep in mind what the method is for:
- qlPCA is descriptive. It fits and interprets one sample: the transformations, loadings and scores describe the data they were fitted on. It is not a predictive model and makes no claim about new data.
- New data only with degree 1.
transform,transform_variablesandinverse_transformare defined for piecewise-linear transformations (degree=1) only. - Linear extrapolation. For a new observation outside the training range of a variable, the
transformation is extended linearly from its first or last segment. Nothing in the data supports it
there, and a single extreme value can dominate the scores.
transformandtransform_variablesthen issue anExtrapolationWarningwith the number of observations and the variables concerned. Validation folds in cross-validation are new data, so expect the warning there. - Heavy tails. With heavy-tailed variables (for example
a/b,b/aand2*a*pi/b^2inmake_cylinder) the scores of new observations can reach values around 100 when the training scores stay within ±2.5. Transform such variables before fitting (e.g.log), or do not project new data.
See docs/DESIGN.md, D10 and D11.
Notebooks
| notebook | source | content |
|---|---|---|
| 01 Spline transformations | thesis §1.1 | B-, M- and I-splines, knots, pseudo-indicator matrix; thesis Fig. 1.1 |
| 02 PCA as loss minimisation | thesis §1.2–1.3 | the common loss function; PCA, MCA and qlPCA as spline classes |
| 03 From CATPCA to qlPCA | thesis ch. 2 | HOMALS and CATPCA in brief; discretisation of continuous variables (Table 2.2) |
| 04 The qlPCA algorithm | thesis §3.1–3.2 | corrected pseudo-code, legacy vs default, properties; Figs 3.1, 3.2 |
| 05 The cylinder problem | thesis §3.3 | simulation study; Table 3.3, Figs 3.4–3.7 (qualitative) |
| 06 Science & technology: gender differences | thesis ch. 4 | the application; Tables 4.1–4.8, Figs 4.1–4.10 (exact) |
| 07 Eurostat economic indicators | WCE 2011 | introduction only (see below) |
The notebooks are stored with their outputs. They import everything from qlpca; no algorithm code is
duplicated in them.
Results compared with the thesis
Chapter 4 is an exact replication (legacy=True). The tolerance for the qlPCA tables is 0.005,
the rounding of the printed two-decimal values.
| thesis | quantity | thesis | this repository | |
|---|---|---|---|---|
| Table 4.1 | summary statistics of the 11 variables | — | max. difference 0.02 | the thesis prints the mean of m_top as 19.4 (data: 19.42) |
| Table 4.3 | PCA eigenvalues | 4.276, 2.531, 1.878, … | 4.276, 2.532, 1.878, … | max. difference 0.0006 |
| Table 4.4 | PCA loadings (absolute values) | — | max. difference 0.005 | |
| Table 4.5 | qlPCA, 1 knot: eigenvalues, % VAF | 4.582, 2.998; 68.90 % | 4.582, 2.998; 68.90 % | |
| Table 4.5 | qlPCA, 2 knots: eigenvalues, % VAF | 4.760, 3.637; 76.33 % | 4.759, 3.637; 76.33 % | |
| Table 4.6 | qlPCA loadings (absolute values) | — | max. difference 0.005 | signs are a convention (see below) |
| Tables 4.7, 4.8 | communalities | — | max. difference 0.005, 0.003 | |
| p. 100 | PCA communality of mf_funds |
0.0244 | 0.0252 | the thesis value comes from the rounded loadings of Table 4.4 |
| Fig. 4.5 | 2 knots, 3 components | scree plot only | 90.00 % (legacy, thesis column order) or 90.30 % | local optima; the result depends on the start, both are reported |
| Fig. 1.1 | $I_1(0.58)$, $I_2(0.58)$, $f(0.58)$ | 1, 0.29, 1.37 | 1, 0.29, 1.37 | |
| Table 2.2 | discretisation by multiplying | — | identical | with the population standard deviation |
Qualitative comparisons, where the thesis data cannot be recovered:
| thesis | quantity | thesis | this repository |
|---|---|---|---|
| Table 3.3 | cylinder problem, % variance in 2 dimensions, PCA / qlPCA 2 knots / qlPCA 3 knots | no noise 82.15 / 97.77 / 98.43; noise 10 % 80.18 / 96.90 / 97.68; noise 25 % 72.62 / 92.59 / 94.41 | means of 50 simulated data sets: 82.67 / 98.14 / 98.80; 80.95 / 96.95 / 97.79; 73.47 / 92.57 / 93.92 (thesis values inside the simulated range in every cell) |
| Fig. 3.4 | PCA scree plot, noise 25 % | two breaks (3rd and 6th component) | one clear break in the simulated draw: not reproduced |
Not reproduced
| source | what | why |
|---|---|---|
| thesis pp. 52–53 | illustrative pseudo-indicator matrices | the printed code gives different values; probably other boundary knots (open question) |
| thesis §2.2.2, ch. 4; WCE Table II | CATPCA results | computed with SPSS |
| WCE 2011, §V | Eurostat example (58 % / 64 % / 54 %) | data values and reference year not printed in the paper; notebook 07 is an introduction only |
Signs. A loading is defined up to sign per component and — for a non-monotone transformation — also
per variable. The package orients each transformed variable so that $\mathrm{corr}(f_j, h_j) \ge 0$ and each
component so that its largest loading is positive (the convention of MATLAB's biplot). Comparisons with the
thesis are made in absolute value or after aligning signs. In the two-knot solution of chapter 4 the
V-shaped variable mf_funds is oriented in opposite ways by the package and by the thesis; the thesis reads
its sign change between one and two knots as substantive (p. 92), but part of it is this indeterminacy.
Tests
python -m pytest # package, thesis tables (legacy), modern default, cylinder study
python tools/run_notebooks.py # execute every notebook
The numbers printed in the thesis and papers that serve as test targets are in
tests/reference_values.json and are never edited to make a test pass.
Data
src/qlpca/data/st_gender_eu15.csv— chapter 4 data, shipped with the package (qlpca.datasets.load_st_gender()) (thesis Appendix A.1): 11 indicators of gender differences in science and technology for 15 EU countries, 2003–2004, compiled by Oliveira & Carvalho (2009) from Eurostat and She Figures 2006, and provided by them for the thesis. Seedata/README.md.- The cylinder data are simulated (
qlpca.datasets.make_cylinder).
How to cite
Please cite the article that describes the method (see also CITATION.cff):
Lavado, N. & Calapez, T. (2011). Principal Components Analysis with Spline Optimal Transformations for Continuous Data. IAENG International Journal of Applied Mathematics, 41(4), 367–375. https://www.iaeng.org/IJAM/issues_v41/issue_4/IJAM_41_4_14.pdf
To cite the software itself (the Zenodo DOI will be added with the first release):
Lavado, N. & Calapez, T. qlpca: quasi-linear PCA in Python, with a replication of the PhD thesis, version 0.2.0. https://github.com/nlavadodatasci/quasi-linear-PCA
Related work:
- Lavado, N. (2012). Extensões via splines da Análise em Componentes Principais. PhD thesis, ISCTE – Instituto Universitário de Lisboa. http://hdl.handle.net/10071/6202
- Lavado, N. & Calapez, T. (2011). Quasi-Linear PCA: Low Order Spline's Approach to Non-Linear Principal Components. Proceedings of the World Congress on Engineering 2011, vol. I, 360–364. http://hdl.handle.net/10071/14371
Full bibliography: references.bib.
Related work and software
qlPCA builds on the Gifi framework of nonlinear multivariate analysis (Gifi, 1990), in which variables
are optimally transformed by alternating least squares; CATPCA (SPSS) belongs to the same family.
The closest software is princals in the R package
Gifi (Mair, De Leeuw & Groenen; GPL-3) and its Python port
pyGifi (GPL-3).
qlpca is an independent implementation, written from the author's PhD thesis (Lavado, 2012) and the
method's original paper (Lavado & Calapez, 2011). It contains no code from the Gifi R package or from
pyGifi.
A numerical comparison with princals (pipelines, same knots, defaults, local optima, monotone fits) is in
comparison/princals/; the two GPL-3 packages are only called there.
- Gifi, A. (1990). Nonlinear Multivariate Analysis. Chichester: Wiley.
Authors
- Nuno Lavado — Coimbra Institute of Engineering (ISEC), Polytechnic University of Coimbra. ORCID 0000-0001-8237-3086.
- Teresa Calapez — ISCTE - Instituto Universitário de Lisboa. ORCID 0000-0002-8584-2906. She supervised the PhD thesis (Lavado, 2012) and is co-author of the paper that introduced qlPCA (Lavado & Calapez, 2011).
Licence
Code, including the code cells of the notebooks: MIT.
Text and figures (notebook prose and outputs, docs/, this README): CC BY 4.0.
The chapter 4 data are not covered by these licences; see data/README.md.
Metadata
Release files for qlpca 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| qlpca-0.2.0.tar.gz | 43.0 kB | With provenance | Details for qlpca-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| qlpca-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for qlpca-0.2.0-py3-none-any.whl |
Total release size: 71.7 kB
Release files / qlpca-0.2.0.tar.gz
| Download URL | qlpca-0.2.0.tar.gz |
|---|---|
| Size | 43.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
64886e6142cb293fff50e7e026f7a109d87258a78ba193704e5c5bfae8d4aa7f
|
|
BLAKE2b-256 checksum How to use checksums |
e0fa86f2fe43613271a80972b5efa4cae4184a109fa3493eae61ac26331c81f6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / qlpca-0.2.0-py3-none-any.whl
| Download URL | qlpca-0.2.0-py3-none-any.whl |
|---|---|
| Size | 28.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
32706362d832fbbc944b475cccc178b263efc554dc64b0bab958f354c396058f
|
|
BLAKE2b-256 checksum How to use checksums |
c12ee00480ebc8937d63e898dae84624ca7b34ee57afa13c08153aca30dc655a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for qlpca 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for qlpca-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.