(defn principal-components
"
  Performs a principal components analysis on the given data matrix.
  Equivalent to R's prcomp function.

  Returns:
    A map with the following fields:
    :std-dev -- the standard deviations of the principal compoenents
        (i.e. the square roots of the eigenvalues of the correlation
        matrix, though the calculation is actually done with the
        singular values of the data matrix.
    :rotation -- the matrix of variable loadings (i.e. a matrix
        whose columns contain the eigenvectors).


  Examples:

    (use '(incanter core stats charts datasets))
    ;; load the iris dataset
    (def iris (to-matrix (get-dataset :iris)))
    ;; run the pca
    (def pca (principal-components (sel iris :cols (range 4))))
    ;; extract the first two principal components
    (def pc1 (sel (:rotation pca) :cols 0))
    (def pc2 (sel (:rotation pca) :cols 1))

    ;; project the first four dimension of the iris data onto the first
    ;; two principal components
    (def x1 (mmult (sel iris :cols (range 4)) pc1))
    (def x2 (mmult (sel iris :cols (range 4)) pc2))

    ;; now plot the transformed data, coloring each species a different color
    (doto (scatter-plot (sel x1 :rows (range 50)) (sel x2 :rows (range 50))
                        :x-label \"PC1\" :y-label \"PC2\" :title \"Iris PCA\")
          (add-points (sel x1 :rows (range 50 100)) (sel x2 :rows (range 50 100)))
          (add-points (sel x1 :rows (range 100 150)) (sel x2 :rows (range 100 150)))
          view)


    ;; alternatively, the :group-by option can be used in scatter-plot
    (view (scatter-plot x1 x2
                        :group-by (sel iris :cols 4)
                        :x-label \"PC1\" :y-label \"PC2\" :title \"Iris PCA\"))


  References:
    http://en.wikipedia.org/wiki/Principal_component_analysis

"
  ([x & options]
   (let [svd (decomp-svd (correlation x))
         rotation (:V svd)
         std-dev (sqrt (:S svd))]
     {:std-dev std-dev
      :rotation rotation})))