math::PCA(n)

✨ math::PCA — Principal Components Analysis ✨

okay bestie, so this is math::PCA(n) from the tcllib girlies, and it's literally the whole Principal Components Analysis situation but in Tcl 💅 like it's giving object-oriented, it's giving TclOO, it's giving "I understand your data's vibe on a deeper level".

---

NAME 🎀

math::PCA — the Package for Principal Component Analysis, no cap 🌸

---

SYNOPSIS 🌈

package require Tcl ?8.6 9?

package require math::linearalgebra 1.1

::math::PCA::createPCA data ?args?

$pca using ?number?|?-minproportion value?

$pca eigenvectors ?option?

$pca eigenvalues ?option?

$pca proportions ?option?

$pca approximate observation

$pca approximatOriginal

$pca scores observation

$pca distance observation

$pca qstatistic observation ?option?

---

DESCRIPTION 🦋

So the PCA package is your girl for doing principal components analysis in Tcl, and it does it with an object-oriented technique as facilitated by TclOO — very demure, very mindful ✨

Real talk though: it actually defines exactly one public method, ::math::PCA::createPCA, and that method constructs an object based on the data you hand it, and that object does the actual analysis. main character energy fr fr 👑

The methods on the PCA objects you create with this command let you:

• peek at the principal components 👀
• approximate (new) observations using all the components, or just a selected number of them
• examine the properties of the components and the statistics of the approximations

And a lil lore drop: this package was modelled after the PCA example provided by the original linear algebra package by Ed Hume. we love an origin story 🫶

---

COMMANDS 🧚

The math::PCA package provides one public command, and here it is:

• ::math::PCA::createPCA data ?args? — Create a new object, based on the data that are passed via the data argument. The principal components may be based on either correlations or covariances. All observations will be normalised according to the mean and standard deviation of the original data. ✨
  • list data — A list of observations (see the example below).
  • list args — A list of key-value pairs defining the options. Currently there is only one key: -covariances. This indicates if covariances are to be used (if the value is 1) or instead correlations (value is 0). The default is to use correlations. 📊

---

the methods on the object you just made 💖

The PCA object that is created has the following methods:

• $pca using ?number?|?-minproportion value? — Set the number of components to be used in the analysis (the number of retained components). Returns the number of components, also if no argument is given.
  • int number — The number of components to be retained
  • double value — Select the number of components based on the minimum proportion of variation that is retained by them. Should be a value between 0 and 1. 🎯
• $pca eigenvectors ?option? — Return the eigenvectors as a list of lists.
  • string option — By default only the retained components are returned. If all eigenvectors are required, use the option -all. 👑
• $pca eigenvalues ?option? — Return the eigenvalues as a list of lists.
  • string option — By default only the eigenvalues of the retained components are returned. If all eigenvalues are required, use the option -all. 🌟
• $pca proportions ?option? — Return the proportions for all components, that is, the amount of variations that each components can explain. 💫
• $pca approximate observation — Return an approximation of the observation based on the retained components.
  • list observation — The values for the observation.
• $pca approximatOriginal — Return an approximation of the original data, using the retained components. It is a convenience method that works on the complete set of original data. (and yes bestie, that really is the spelling, approximatOriginal, no I will not be fixing it, the manpage said what it said 🙈)
• $pca scores observation — Return the scores per retained component for the given observation.
  • list observation — The values for the observation.
• $pca distance observation — Return the distance between the given observation and its approximation. (Note: this distance is based on the normalised vectors.)
  • list observation — The values for the observation.
• $pca qstatistic observation ?option? — Return the Q statistic, basically the square of the distance, for the given observation.
  • list observation — The values for the observation.
  • string option — If the observation is part of the original data, you may want to use the corrected Q statistic. This is achieved with the option "-original". 🔥

---

EXAMPLE 🌸

TODO: NIST example

ngl the manpage literally just says TODO: NIST example here. we're all waiting on that one together bestie 😭🫶

---

BUGS, IDEAS, FEEDBACK 💀

This document, and the package it describes, will undoubtedly contain bugs and other problems. (the self-awareness? iconic.) Please report such in the category PCA of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas for enhancements you may have for either package and/or documentation. we love a feedback loop 💖

When proposing code changes, please provide unified diffs, i.e the output of diff -u. no vibe-based patches pls, give us the real diff 📝

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. 🎀

---

KEYWORDS 🦋

PCA, math, statistics, tcl

---

CATEGORY 👑

Mathematics

---

and that's the whole page bestie — this one ships as part of tcllib at version 1.1, and the page you're reading is math::PCA(n) at that same 1.1, dated like the tcllib release it rode in on. slay, go analyse some components, you got this 💅✨🌸