| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> |
| <meta http-equiv="X-UA-Compatible" content="IE=9"/> |
| <meta name="generator" content="Doxygen 1.8.4"/> |
| <title>MADlib: PCA Projection</title> |
| <link href="tabs.css" rel="stylesheet" type="text/css"/> |
| <script type="text/javascript" src="jquery.js"></script> |
| <script type="text/javascript" src="dynsections.js"></script> |
| <link href="navtree.css" rel="stylesheet" type="text/css"/> |
| <script type="text/javascript" src="resize.js"></script> |
| <script type="text/javascript" src="navtree.js"></script> |
| <script type="text/javascript"> |
| $(document).ready(initResizable); |
| $(window).load(resizeHeight); |
| </script> |
| <link href="search/search.css" rel="stylesheet" type="text/css"/> |
| <script type="text/javascript" src="search/search.js"></script> |
| <script type="text/javascript"> |
| $(document).ready(function() { searchBox.OnSelectItem(0); }); |
| </script> |
| <script type="text/x-mathjax-config"> |
| MathJax.Hub.Config({ |
| extensions: ["tex2jax.js", "TeX/AMSmath.js", "TeX/AMSsymbols.js"], |
| jax: ["input/TeX","output/HTML-CSS"], |
| }); |
| </script><script src="../mathjax/MathJax.js"></script> |
| <link href="doxygen.css" rel="stylesheet" type="text/css" /> |
| </head> |
| <body> |
| <div id="top"><!-- do not remove this div, it is closed by doxygen! --> |
| <div id="titlearea"> |
| <table cellspacing="0" cellpadding="0"> |
| <tbody> |
| <tr style="height: 56px;"> |
| <td style="padding-left: 0.5em;"> |
| <div id="projectname">MADlib |
|  <span id="projectnumber">1.1</span> <span style="font-size:10pt; font-style:italic"><a href="../latest/./group__grp__pca__project.html"> A newer version is available</a></span> |
| </div> |
| <div id="projectbrief">User Documentation</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <!-- end header part --> |
| <!-- Generated by Doxygen 1.8.4 --> |
| <script type="text/javascript"> |
| var searchBox = new SearchBox("searchBox", "search",false,'Search'); |
| </script> |
| <div id="navrow1" class="tabs"> |
| <ul class="tablist"> |
| <li><a href="index.html"><span>Main Page</span></a></li> |
| <li><a href="modules.html"><span>Modules</span></a></li> |
| <li><a href="files.html"><span>Files</span></a></li> |
| <li> |
| <div id="MSearchBox" class="MSearchBoxInactive"> |
| <span class="left"> |
| <img id="MSearchSelect" src="search/mag_sel.png" |
| onmouseover="return searchBox.OnSearchSelectShow()" |
| onmouseout="return searchBox.OnSearchSelectHide()" |
| alt=""/> |
| <input type="text" id="MSearchField" value="Search" accesskey="S" |
| onfocus="searchBox.OnSearchFieldFocus(true)" |
| onblur="searchBox.OnSearchFieldFocus(false)" |
| onkeyup="searchBox.OnSearchFieldChange(event)"/> |
| </span><span class="right"> |
| <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a> |
| </span> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div><!-- top --> |
| <div id="side-nav" class="ui-resizable side-nav-resizable"> |
| <div id="nav-tree"> |
| <div id="nav-tree-contents"> |
| <div id="nav-sync" class="sync"></div> |
| </div> |
| </div> |
| <div id="splitbar" style="-moz-user-select:none;" |
| class="ui-resizable-handle"> |
| </div> |
| </div> |
| <script type="text/javascript"> |
| $(document).ready(function(){initNavTree('group__grp__pca__project.html','');}); |
| </script> |
| <div id="doc-content"> |
| <!-- window showing the filter options --> |
| <div id="MSearchSelectWindow" |
| onmouseover="return searchBox.OnSearchSelectShow()" |
| onmouseout="return searchBox.OnSearchSelectHide()" |
| onkeydown="return searchBox.OnSearchSelectKey(event)"> |
| <a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Groups</a></div> |
| |
| <!-- iframe showing the search results (closed by default) --> |
| <div id="MSearchResultsWindow"> |
| <iframe src="javascript:void(0)" frameborder="0" |
| name="MSearchResults" id="MSearchResults"> |
| </iframe> |
| </div> |
| |
| <div class="header"> |
| <div class="headertitle"> |
| <div class="title">PCA Projection<div class="ingroups"><a class="el" href="group__grp__pca.html">Principal Component Analysis</a></div></div> </div> |
| </div><!--header--> |
| <div class="contents"> |
| <div id="dynsection-0" onclick="return toggleVisibility(this)" class="dynheader closed" style="cursor:pointer;"> |
| <img id="dynsection-0-trigger" src="closed.png" alt="+"/> Collaboration diagram for PCA Projection:</div> |
| <div id="dynsection-0-summary" class="dynsummary" style="display:block;"> |
| </div> |
| <div id="dynsection-0-content" class="dyncontent" style="display:none;"> |
| <center><table><tr><td><div class="center"><iframe scrolling="no" frameborder="0" src="group__grp__pca__project.svg" width="328" height="56"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe> |
| </div> |
| </td></tr></table></center> |
| </div> |
| <div class="toc"><b>Contents</b> </p> |
| <ul> |
| <li class="level1"> |
| <a href="#pca_train">About</a> </li> |
| <li class="level1"> |
| <a href="#help">Online Help</a> </li> |
| <li class="level1"> |
| <a href="#train">Training Function</a> </li> |
| <li class="level1"> |
| <a href="#output">Output Tables</a> </li> |
| <li class="level1"> |
| <a href="#examples">Examples</a> </li> |
| <li class="level1"> |
| <a href="#seealso">See Also</a> </li> |
| <li class="level1"> |
| <a href="#background">Technical Background</a> </li> |
| </ul> |
| </div><p><a class="anchor" id="about"></a></p> |
| <dl class="section user"><dt>About:</dt><dd></dd></dl> |
| <p>Principal component projection is a mathematical procedure that projects high dimensional data onto a lower dimensional space. This lower dimensional space is defined by the \( k \) principal components with the highest variance in the training data. More details on the mathematics of PCA can be found in <a class="el" href="group__grp__pca__train.html#pca_train">pca_train</a> and some details about the principal component projection calculations can be found in the <a class="el" href="group__grp__pca__project.html#background">Technical Background</a>.</p> |
| <p><a class="anchor" id="help"></a></p> |
| <dl class="section user"><dt>Online Help</dt><dd></dd></dl> |
| <p>View short help messages using the following statements: </p> |
| <pre class="fragment">-- Summary of PCA projection |
| madlib.pca_project() |
| madlib.pca_project('?') |
| madlib.pca_project('help') |
| |
| -- Projection function syntax and output table format |
| madlib.pca_project('usage') |
| |
| -- Summary of PCA projection with sparse matrices |
| madlib.pca_sparse_project() |
| madlib.pca_sparse_project('?') |
| madlib.pca_sparse_project('help') |
| |
| -- Projection function syntax and output table format |
| madlib.pca_sparse_project('usage') |
| </pre><p><a class="anchor" id="train"></a></p> |
| <dl class="section user"><dt>Training Function</dt><dd>The training functions have the following formats: <pre class="fragment">madlib.pca_project( source_table, pc_table, out_table, row_id, |
| residual_table := NULL, result_summary_table := NULL) |
| </pre> and <pre class="fragment">madlib.pca_sparse_project( source_table, pc_table, out_table, row_id, |
| col_id, val_id, row_dim, col_dim, residual_table := NULL, |
| result_summary_table := NULL) |
| </pre> </dd></dl> |
| <dl class="section note"><dt>Note</dt><dd>This function is intended to operate on the principal component tables generated by <em> pca_train </em> or <em> pca_sparse_train</em>. The MADlib PCA functions generate a table containing the column-means in addition to a table containing the principal components. If this table is not found by the MADlib projection function, it will trigger an error. As long the principal component tables are created with MADlib functions, then the column-means table will be automatically found by the MADlib projection functions.</dd> |
| <dd> |
| Because of the centering step in PCA projection (see <a class="el" href="group__grp__pca__project.html#background">Technical Background</a>), sparse matrices almost always become dense during the projection process. Thus, this implementation automatically densifies sparse matrix input, and there should be no expected performance improvement in using sparse matrix input over dense matrix input.</dd></dl> |
| <dl class="section user"><dt>Arguments</dt><dd><dl class="arglist"> |
| <dt>source_table </dt> |
| <dd><p class="startdd">Text value. Source table name. Identical to <a class="el" href="group__grp__pca__train.html#pca_train">pca_train</a>, the input data matrix should have \( N \) rows and \( M \) columns, where \( N \) is the number of data points, and \( M \) is the number of features for each data point.</p> |
| <p>The input table for <em> pca_project </em> is expected to be in the one of the two standard MADlib dense matrix formats, and the sparse input table for <em> pca_sparse_project </em> should be in the standard MADlib sparse matrix format. These formats are described in the documentation for <a class="el" href="group__grp__pca__train.html#pca_train">pca_train</a>.</p> |
| <p class="enddd"></p> |
| </dd> |
| <dt>pc_table </dt> |
| <dd><p class="startdd">Text value. Table name for the table containing principal components. </p> |
| <p class="enddd"></p> |
| </dd> |
| <dt>out_table </dt> |
| <dd><p class="startdd">Text value. Name of the table that will contain the low-dimensional representation of the input data.</p> |
| <p class="enddd"></p> |
| </dd> |
| <dt>row_id </dt> |
| <dd><p class="startdd">Text value. Column name containing the row IDs in the input source table.</p> |
| <p class="enddd"></p> |
| </dd> |
| <dt>col_id </dt> |
| <dd><p class="startdd">Text value. Name of 'col_id' column in sparse matrix representation (sparse matrices only). </p> |
| <p class="enddd"></p> |
| </dd> |
| <dt>val_id </dt> |
| <dd><p class="startdd">Text value. Name of 'val_id' column in sparse matrix representation (sparse matrices only). </p> |
| <p class="enddd"></p> |
| </dd> |
| <dt>row_dim </dt> |
| <dd><p class="startdd">Integer value. The number of rows in the sparse matrix (sparse matrices only). </p> |
| <p class="enddd"></p> |
| </dd> |
| <dt>col_dim </dt> |
| <dd><p class="startdd">Integer value. The number of columns in the sparse matrix (sparse matrices only). </p> |
| <p class="enddd"></p> |
| </dd> |
| <dt>residual_table </dt> |
| <dd><p class="startdd">Text value. Name of the optional residual table. Default: NULL.</p> |
| <p class="enddd"></p> |
| </dd> |
| <dt>result_summary_table </dt> |
| <dd>Text value. Name of the optional summary table. Default: NULL. </dd> |
| </dl> |
| </dd></dl> |
| <p><a class="anchor" id="output"></a></p> |
| <dl class="section user"><dt>Output Tables</dt><dd></dd></dl> |
| <p>The output is divided into three tables (two of which are optional).</p> |
| <p>The output table ('<em>out_table</em>' above) encodes a dense matrix with the projection onto the principal components. The table has the following columns: </p> |
| <dl class="section user"><dt></dt><dd><dl class="arglist"> |
| <dt>row_id </dt> |
| <dd>Row id of the output matrix. </dd> |
| <dt>row_vec </dt> |
| <dd>A vector containing elements in the row of the matrix. </dd> |
| </dl> |
| </dd></dl> |
| <p>The residual table ('<em>residual_table</em>' above) encodes a dense residual matrix. The table has the following columns: </p> |
| <dl class="section user"><dt></dt><dd><dl class="arglist"> |
| <dt>row_id </dt> |
| <dd>Row id of the output matrix. </dd> |
| <dt>row_vec </dt> |
| <dd>A vector containing elements in the row of the residual matrix. </dd> |
| </dl> |
| </dd></dl> |
| <p>The result summary table ('<em>result_summary_table</em>' above) contains information about the performance time of the PCA projection. The table has the following columns: </p> |
| <dl class="section user"><dt></dt><dd><dl class="arglist"> |
| <dt>exec_time </dt> |
| <dd>Wall clock time (ms) of the function. </dd> |
| <dt>residual_norm </dt> |
| <dd>Absolute error of the residuals. </dd> |
| <dt>relative_residual_norm </dt> |
| <dd>Relative error of the residuals. </dd> |
| </dl> |
| </dd></dl> |
| <p><a class="anchor" id="examples"></a></p> |
| <dl class="section user"><dt>Examples:</dt><dd><ol type="1"> |
| <li>Create the sample data. <pre class="fragment">sql> DROP TABLE IF EXISTS mat; |
| sql> CREATE TABLE mat ( |
| row_id integer, |
| row_vec double precision[] |
| ); |
| |
| sql> COPY mat (row_id, row_vec) FROM stdin; |
| 1 {1,2,5} |
| 0 {4,7,5} |
| 3 {9,2,4} |
| 2 {7,4,4} |
| 5 {0,5,5} |
| 4 {8,5,7} |
| \.</pre></li> |
| <li>Run the PCA function and keep only the top two PCs: <pre class="fragment">sql> DROP TABLE IF EXISTS result_table; |
| sql> SELECT pca_train( |
| 'mat', -- name of the input table |
| 'result_table', -- name of the output table |
| 'row_id', -- column containing the matrix indices |
| 2 -- Number of PCA components to compute |
| ); |
| </pre></li> |
| <li>Project the original data into a low-dimensional representation. <pre class="fragment">sql> DROP TABLE IF EXISTS residual_table, result_summary_table, out_table; |
| sql> SELECT pca_project( |
| 'mat', -- name of the input table |
| 'result_table', -- name of the table containing the PCs |
| 'out_table' -- name of the table containing the projection |
| 'row_id', -- column containing the input matrix indices |
| 'residual_table', -- Name of the optional residual table |
| 'result_summary_table' -- Name of the optional summary table |
| ); |
| </pre></li> |
| <li>Check the error in the projection. <pre class="fragment">sql> SELECT * FROM result_summary_table; |
| exec_time | residual_norm | relative_residual_norm |
| ---------------+---------------+------------------------ |
| 5685.40501595 | 2.19726255664 | 0.099262204234 |
| </pre></li> |
| </ol> |
| </dd></dl> |
| <p><a class="anchor" id="seealso"></a></p> |
| <dl class="section see"><dt>See Also</dt><dd>File <a class="el" href="pca__project_8sql__in.html" title="Principal Component Analysis Projection. ">pca_project.sql_in</a> documenting the SQL functions. </dd> |
| <dd> |
| <a class="el" href="group__grp__pca__train.html">PCA Training</a></dd></dl> |
| <p><a class="anchor" id="background"></a></p> |
| <dl class="section user"><dt>Technical Background</dt><dd></dd></dl> |
| <p>Given a table containing some principal components \( \boldsymbol P \) and some input data \( \boldsymbol X \), the low-dimensional representation \( {\boldsymbol X}' \) is computed as </p> |
| <p class="formulaDsp"> |
| \begin{align*} {\boldsymbol {\hat{X}}} & = {\boldsymbol X} - \vec{e} \hat{x}^T \\ {\boldsymbol X}' & = {\boldsymbol {\hat {X}}} {\boldsymbol P}. \end{align*} |
| </p> |
| <p> where \(\hat{x} \) is the column means of \( \boldsymbol X \) and \( \vec{e} \) is the vector of all ones. This step is equivalent to centering the data around the origin.</p> |
| <p>The residual table \( \boldsymbol R \) is a measure of how well the low-dimensional representation approximates the true input data, and is computed as </p> |
| <p class="formulaDsp"> |
| \[ {\boldsymbol R} = {\boldsymbol {\hat{X}}} - {\boldsymbol X}' {\boldsymbol P}^T. \] |
| </p> |
| <p> A residual matrix with entries mostly close to zero indicates a good representation.</p> |
| <p>The residual norm \( r \) is simply </p> |
| <p class="formulaDsp"> |
| \[ r = \|{\boldsymbol R}\|_F \] |
| </p> |
| <p> where \( \|\cdot\|_F \) is the Frobenius norm. The relative residual norm \( r' \) is </p> |
| <p class="formulaDsp"> |
| \[ r' = \frac{ \|{\boldsymbol R}\|_F }{\|{\boldsymbol X}\|_F } \] |
| </p> |
| </div><!-- contents --> |
| </div><!-- doc-content --> |
| <!-- start footer part --> |
| <div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> |
| <ul> |
| <li class="footer">Generated on Wed Aug 21 2013 16:09:52 for MADlib by |
| <a href="http://www.doxygen.org/index.html"> |
| <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.4 </li> |
| </ul> |
| </div> |
| </body> |
| </html> |
