NAME

       math::PCA - Package for Principal Component Analysis

SYNOPSIS

       package require Tcl  ?8.6?

       package require math::linearalgebra  1.0

       ::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

       The PCA package provides a means to perform principal components analysis in Tcl, using an
       object-oriented technique as facilitated by TclOO. It actually  defines  a  single  public
       method,  ::math::PCA::createPCA,  which  constructs  an  object based on the data that are
       passed to perform the actual analysis.

       The methods of the PCA objects that are created with this command allow one to examine the
       principal  components, to approximate (new) observations using all or a selected number of
       components only and to examine the properties of the components and the statistics of  the
       approximations.

       The  package  has  been  modelled  after  the  PCA example provided by the original linear
       algebra package by Ed Hume.

COMMANDS

       The math::PCA package provides one public command:

       ::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 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.

       $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

BUGS, IDEAS, FEEDBACK

       This  document,  and  the  package  it  describes, will undoubtedly contain bugs and other
       problems.   Please  report  such  in   the   category   PCA   of   the   Tcllib   Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       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