http://git-wip-us.apache.org/repos/asf/madlib-site/blob/af0e5f14/docs/v1.15.1/group__grp__pca.html ---------------------------------------------------------------------- diff --git a/docs/v1.15.1/group__grp__pca.html b/docs/v1.15.1/group__grp__pca.html new file mode 100644 index 0000000..b90ca73 --- /dev/null +++ b/docs/v1.15.1/group__grp__pca.html @@ -0,0 +1,149 @@ +<!-- HTML header for doxygen 1.8.4--> +<!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.14"/> +<meta name="keywords" content="madlib,postgres,greenplum,machine learning,data mining,deep learning,ensemble methods,data science,market basket analysis,affinity analysis,pca,lda,regression,elastic net,huber white,proportional hazards,k-means,latent dirichlet allocation,bayes,support vector machines,svm"/> +<title>MADlib: Dimensionality Reduction</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="navtreedata.js"></script> +<script type="text/javascript" src="navtree.js"></script> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ + $(document).ready(initResizable); +/* @license-end */</script> +<link href="search/search.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="search/searchdata.js"></script> +<script type="text/javascript" src="search/search.js"></script> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ + $(document).ready(function() { init_search(); }); +/* @license-end */ +</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 type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js";></script> +<!-- hack in the navigation tree --> +<script type="text/javascript" src="eigen_navtree_hacks.js"></script> +<link href="doxygen.css" rel="stylesheet" type="text/css" /> +<link href="madlib_extra.css" rel="stylesheet" type="text/css"/> +<!-- google analytics --> +<script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + ga('create', 'UA-45382226-1', 'madlib.apache.org'); + ga('send', 'pageview'); +</script> +</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 id="projectlogo"><a href="http://madlib.apache.org";><img alt="Logo" src="madlib.png" height="50" style="padding-left:0.5em;" border="0"/ ></a></td> + <td style="padding-left: 0.5em;"> + <div id="projectname"> + <span id="projectnumber">1.15.1</span> + </div> + <div id="projectbrief">User Documentation for Apache MADlib</div> + </td> + <td> <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> +</td> + </tr> + </tbody> +</table> +</div> +<!-- end header part --> +<!-- Generated by Doxygen 1.8.14 --> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +var searchBox = new SearchBox("searchBox", "search",false,'Search'); +/* @license-end */ +</script> +</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"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +$(document).ready(function(){initNavTree('group__grp__pca.html','');}); +/* @license-end */ +</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)"> +</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="summary"> +<a href="#groups">Modules</a> </div> + <div class="headertitle"> +<div class="title">Dimensionality Reduction<div class="ingroups"><a class="el" href="group__grp__unsupervised.html">Unsupervised Learning</a></div></div> </div> +</div><!--header--> +<div class="contents"> +<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2> +<p>Methods for reducing the number of variables in a dataset to obtain a set of principle variables. </p> +<table class="memberdecls"> +<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="groups"></a> +Modules</h2></td></tr> +<tr class="memitem:group__grp__pca__train"><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__grp__pca__train.html">Principal Component Analysis</a></td></tr> +<tr class="memdesc:group__grp__pca__train"><td class="mdescLeft"> </td><td class="mdescRight">Produces a model that transforms a number of (possibly) correlated variables into a (smaller) number of uncorrelated variables called principal components. <br /></td></tr> +<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr> +<tr class="memitem:group__grp__pca__project"><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__grp__pca__project.html">Principal Component Projection</a></td></tr> +<tr class="memdesc:group__grp__pca__project"><td class="mdescLeft"> </td><td class="mdescRight">Projects a higher dimensional data point to a lower dimensional subspace spanned by principal components learned through the PCA training procedure. <br /></td></tr> +<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr> +</table> +</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 Mon Oct 15 2018 11:24:30 for MADlib by + <a href="http://www.doxygen.org/index.html";> + <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.14 </li> + </ul> +</div> +</body> +</html>
http://git-wip-us.apache.org/repos/asf/madlib-site/blob/af0e5f14/docs/v1.15.1/group__grp__pca.js ---------------------------------------------------------------------- diff --git a/docs/v1.15.1/group__grp__pca.js b/docs/v1.15.1/group__grp__pca.js new file mode 100644 index 0000000..2863cf8 --- /dev/null +++ b/docs/v1.15.1/group__grp__pca.js @@ -0,0 +1,5 @@ +var group__grp__pca = +[ + [ "Principal Component Analysis", "group__grp__pca__train.html", null ], + [ "Principal Component Projection", "group__grp__pca__project.html", null ] +]; \ No newline at end of file http://git-wip-us.apache.org/repos/asf/madlib-site/blob/af0e5f14/docs/v1.15.1/group__grp__pca__project.html ---------------------------------------------------------------------- diff --git a/docs/v1.15.1/group__grp__pca__project.html b/docs/v1.15.1/group__grp__pca__project.html new file mode 100644 index 0000000..d2a418f --- /dev/null +++ b/docs/v1.15.1/group__grp__pca__project.html @@ -0,0 +1,506 @@ +<!-- HTML header for doxygen 1.8.4--> +<!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.14"/> +<meta name="keywords" content="madlib,postgres,greenplum,machine learning,data mining,deep learning,ensemble methods,data science,market basket analysis,affinity analysis,pca,lda,regression,elastic net,huber white,proportional hazards,k-means,latent dirichlet allocation,bayes,support vector machines,svm"/> +<title>MADlib: Principal Component 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="navtreedata.js"></script> +<script type="text/javascript" src="navtree.js"></script> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ + $(document).ready(initResizable); +/* @license-end */</script> +<link href="search/search.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="search/searchdata.js"></script> +<script type="text/javascript" src="search/search.js"></script> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ + $(document).ready(function() { init_search(); }); +/* @license-end */ +</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 type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js";></script> +<!-- hack in the navigation tree --> +<script type="text/javascript" src="eigen_navtree_hacks.js"></script> +<link href="doxygen.css" rel="stylesheet" type="text/css" /> +<link href="madlib_extra.css" rel="stylesheet" type="text/css"/> +<!-- google analytics --> +<script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + ga('create', 'UA-45382226-1', 'madlib.apache.org'); + ga('send', 'pageview'); +</script> +</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 id="projectlogo"><a href="http://madlib.apache.org";><img alt="Logo" src="madlib.png" height="50" style="padding-left:0.5em;" border="0"/ ></a></td> + <td style="padding-left: 0.5em;"> + <div id="projectname"> + <span id="projectnumber">1.15.1</span> + </div> + <div id="projectbrief">User Documentation for Apache MADlib</div> + </td> + <td> <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> +</td> + </tr> + </tbody> +</table> +</div> +<!-- end header part --> +<!-- Generated by Doxygen 1.8.14 --> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +var searchBox = new SearchBox("searchBox", "search",false,'Search'); +/* @license-end */ +</script> +</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"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +$(document).ready(function(){initNavTree('group__grp__pca__project.html','');}); +/* @license-end */ +</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)"> +</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">Principal Component Projection<div class="ingroups"><a class="el" href="group__grp__unsupervised.html">Unsupervised Learning</a> » <a class="el" href="group__grp__pca.html">Dimensionality Reduction</a></div></div> </div> +</div><!--header--> +<div class="contents"> +<div class="toc"><b>Contents</b> <ul> +<li class="level1"> +<a href="#project">Projection Function</a> </li> +<li class="level1"> +<a href="#examples">Examples</a> </li> +<li class="level1"> +<a href="#notes">Notes</a> </li> +<li class="level1"> +<a href="#background_project">Technical Background</a> </li> +<li class="level1"> +<a href="#related">Related Topics</a> </li> +</ul> +</div><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.</p> +<p>More details on the mathematics of PCA can be found in <a class="el" href="group__grp__pca__train.html">Principal Component Analysis</a> and some details about principal component projection calculations can be found in the <a class="el" href="group__grp__pca__project.html#background_project">Technical Background</a>.</p> +<p><a class="anchor" id="project"></a></p><dl class="section user"><dt>Projection Function</dt><dd>The projection functions are slightly different for dense and sparse matrices. For dense matrices: <pre class="syntax"> +madlib.pca_project( source_table, + pc_table, + out_table, + row_id, + residual_table, + result_summary_table + ) +</pre> For sparse matrices: <pre class="syntax"> +madlib.pca_sparse_project( source_table, + pc_table, + out_table, + row_id, + col_id, -- Sparse matrices only + val_id, -- Sparse matrices only + row_dim, -- Sparse matrices only + col_dim, -- Sparse matrices only + residual_table, + result_summary_table + ) +</pre></dd></dl> +<p><b>Arguments</b> </p><dl class="arglist"> +<dt>source_table </dt> +<dd><p class="startdd">TEXT. Source table name. Identical to <a class="el" href="pca_8sql__in.html#a31abf88e67a446a4f789764aa2c61e85">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">Principal Component Analysis</a>.</p> +<p class="enddd"></p> +</dd> +<dt>pc_table </dt> +<dd><p class="startdd">TEXT. Table name for the table containing principal components. </p> +<p class="enddd"></p> +</dd> +<dt>out_table </dt> +<dd><p class="startdd">TEXT. Name of the table that will contain the low-dimensional representation of the input data.</p> +<p>The <em>out_table</em> encodes a dense matrix with the projection onto the principal components. The table has the following columns:</p> +<table class="output"> +<tr> +<th>row_id </th><td>Row id of the output matrix. </td></tr> +<tr> +<th>row_vec </th><td>A vector containing elements in the row of the matrix. </td></tr> +</table> +<p class="enddd"></p> +</dd> +<dt>row_id </dt> +<dd><p class="startdd">TEXT. Column name containing the row IDs in the input source table. The column should be of type INT (or a type that can be cast to INT) and should only contain values between 1 and <em>N</em>. For dense matrix format, it should contain all continguous integers from 1 to <em>N</em> describing the full matrix.</p> +<p class="enddd"></p> +</dd> +<dt>col_id </dt> +<dd><p class="startdd">TEXT. Column name containing the column IDs in sparse matrix representation. The column should be of type INT (or a type that can be cast to INT) and should only contain values between 1 and <em>M</em>. <em>This parameter applies to sparse matrices only.</em></p> +<p class="enddd"></p> +</dd> +<dt>val_id </dt> +<dd><p class="startdd">TEXT. Name of 'val_id' column in sparse matrix representation defining the values of the nonzero entries. <em>This parameter applies to sparse matrices only.</em></p> +<p class="enddd"></p> +</dd> +<dt>row_dim </dt> +<dd><p class="startdd">INTEGER. The actual number of rows in the matrix. That is, if the matrix was transformed into dense format, this is the number of rows it would have. <em>This parameter applies to sparse matrices only.</em></p> +<p class="enddd"></p> +</dd> +<dt>col_dim </dt> +<dd><p class="startdd">INTEGER. The actual number of columns in the matrix. That is, if the matrix was transformed into dense format, this is the number of columns it would have. <em>This parameter applies to sparse matrices only.</em></p> +<dl class="section note"><dt>Note</dt><dd>The parameters 'row_dim' and 'col_dim' could actually be inferred from the sparse matrix representation, so they will be removed in the future. For now they are maintained for backward compatability so you must enter them. Making 'row_dim' or 'col_dim' larger than the actual matrix has the effect of padding it with zeros, which is probably not useful.</dd></dl> +</dd> +<dt>residual_table (optional) </dt> +<dd><p class="startdd">TEXT, default: NULL. Name of the optional residual table.</p> +<p>The <em>residual_table</em> encodes a dense residual matrix. The table has the following columns:</p> +<table class="output"> +<tr> +<th>row_id </th><td>Row id of the output matrix. </td></tr> +<tr> +<th>row_vec </th><td>A vector containing elements in the row of the residual matrix. </td></tr> +</table> +<p class="enddd"></p> +</dd> +<dt>result_summary_table (optional) </dt> +<dd><p class="startdd">TEXT, default: NULL. Name of the optional summary table.</p> +<p class="enddd">The <em>result_summary_table</em> contains information about the performance time of the PCA projection. The table has the following columns: </p><table class="output"> +<tr> +<th>exec_time </th><td>Elapsed time (ms) for execution of the function. </td></tr> +<tr> +<th>residual_norm </th><td>Absolute error of the residuals. </td></tr> +<tr> +<th>relative_residual_norm </th><td>Relative error of the residuals. </td></tr> +</table> +</dd> +</dl> +<p><a class="anchor" id="examples"></a></p><dl class="section user"><dt>Examples</dt><dd><ol type="1"> +<li>View online help for the PCA projection function: <pre class="example"> +SELECT madlib.pca_project(); +</pre></li> +<li>Create sample data in dense matrix form: <pre class="example"> +DROP TABLE IF EXISTS mat; +CREATE TABLE mat (id integer, + row_vec double precision[] + ); +INSERT INTO mat VALUES +(1, '{1,2,3}'), +(2, '{2,1,2}'), +(3, '{3,2,1}'); +</pre></li> +<li>Run the PCA function for a specified number of principal components and view the results: <pre class="example"> +DROP TABLE IF EXISTS result_table, result_table_mean; +SELECT madlib.pca_train('mat', -- Source table + 'result_table', -- Output table + 'id', -- Row id of source table + 2); -- Number of principal components +SELECT * FROM result_table ORDER BY row_id; +</pre> <pre class="result"> + row_id | principal_components | std_dev | proportion +--------+--------------------------------------------------------------+-------------------+------------------- + 1 | {0.707106781186547,-6.93889390390723e-18,-0.707106781186548} | 1.41421356237309 | 0.857142857142244 + 2 | {0,1,0} | 0.577350269189626 | 0.142857142857041 +(2 rows) +</pre></li> +<li>Project the original data to a lower dimensional representation and view the result of the projection: <pre class="example"> +DROP TABLE IF EXISTS residual_table, result_summary_table, out_table; +SELECT madlib.pca_project( 'mat', + 'result_table', + 'out_table', + 'id', + 'residual_table', + 'result_summary_table' + ); +SELECT * FROM out_table ORDER BY row_id; +</pre> <pre class="result"> + row_id | row_vec +--------+-------------------------------------- + 1 | {-1.41421356237309,-0.33333333333} + 2 | {2.77555756157677e-17,0.66666666667} + 3 | {1.41421356237309,-0.33333333333} +(3 rows) +</pre> Check the error in the projection: <pre class="example"> +SELECT * FROM result_summary_table; +</pre> <pre class="result"> + exec_time | residual_norm | relative_residual_norm +---------------+-------------------+------------------------ + 331.792116165 | 5.89383520611e-16 | 9.68940539229e-17 +(1 row) +</pre> Check the residuals: <pre class="example"> +SELECT * FROM residual_table ORDER BY row_id; +</pre> <pre class="result"> + row_id | row_vec +--------+-------------------------------------------------------------------- + 1 | {-2.22044604925031e-16,-1.11022302462516e-16,3.33066907387547e-16} + 2 | {-1.12243865646685e-18,0,4.7381731349413e-17} + 3 | {2.22044604925031e-16,1.11022302462516e-16,-3.33066907387547e-16} +(3 rows) +</pre></li> +<li>Now we use grouping in dense form to learn different models for different groups. First, we create sample data in dense matrix form with a grouping column. Note we actually have different matrix sizes for the different groups, which is allowed for dense: <pre class="example"> +DROP TABLE IF EXISTS mat_group; +CREATE TABLE mat_group ( + id integer, + row_vec double precision[], + matrix_id integer +); +INSERT INTO mat_group VALUES +(1, '{1,2,3}', 1), +(2, '{2,1,2}', 1), +(3, '{3,2,1}', 1), +(4, '{1,2,3,4,5}', 2), +(5, '{2,5,2,4,1}', 2), +(6, '{5,4,3,2,1}', 2); +</pre></li> +<li>Run the PCA function with grouping for a specified proportion of variance and view the results: <pre class="example"> +DROP TABLE IF EXISTS result_table_group, result_table_group_mean; +SELECT madlib.pca_train('mat_group', -- Source table + 'result_table_group', -- Output table + 'id', -- Row id of source table + 0.8, -- Proportion of variance + 'matrix_id'); -- Grouping column +SELECT * FROM result_table_group ORDER BY matrix_id, row_id; +</pre> <pre class="result"> + row_id | principal_components | std_dev | proportion | matrix_id +--------+------------------------------------------------------------------------------------------------+-----------------+-------------------+----------- + 1 | {0.707106781186548,0,-0.707106781186547} | 1.4142135623731 | 0.857142857142245 | 1 + 1 | {-0.555378486712784,-0.388303582074091,0.0442457354870796,0.255566375612852,0.688115693174023} | 3.2315220311722 | 0.764102534485173 | 2 + 2 | {0.587384101786277,-0.485138064894743,0.311532046315153,-0.449458074050715,0.347212037159181} | 1.795531127192 | 0.235897465516047 | 2 +(3 rows) +</pre></li> +<li>Run the PCA projection on subsets of an input table based on grouping columns. Note that the parameter 'pc_table' used for projection must be generated in training using the same grouping columns. <pre class="example"> +DROP TABLE IF EXISTS mat_group_projected; +SELECT madlib.pca_project('mat_group', + 'result_table_group', + 'mat_group_projected', + 'id'); +SELECT * FROM mat_group_projected ORDER BY matrix_id, row_id; +</pre> <pre class="result"> + row_id | row_vec | matrix_id +--------+---------------------------------------+----------- + 1 | {1.4142135623731} | 1 + 2 | {7.40148683087139e-17} | 1 + 3 | {-1.4142135623731} | 1 + 4 | {-3.59290479201926,0.559694003674779} | 2 + 5 | {0.924092949098971,-2.00871628417505} | 2 + 6 | {2.66881184290186,1.44902228049511} | 2 +(6 rows) +</pre></li> +<li>Now let's look at sparse matrices. Create sample data in sparse matrix form: <pre class="example"> +DROP TABLE IF EXISTS mat_sparse; +CREATE TABLE mat_sparse ( + row_id integer, + col_id integer, + value double precision +); +INSERT INTO mat_sparse VALUES +(1, 1, 1.0), +(2, 2, 2.0), +(3, 3, 3.0), +(4, 4, 4.0), +(1, 5, 5.0), +(2, 4, 6.0), +(3, 2, 7.0), +(4, 3, 8.0); +</pre> As an aside, this is what the sparse matrix above looks like when put in dense form: <pre class="example"> +DROP TABLE IF EXISTS mat_dense; +SELECT madlib.matrix_densify('mat_sparse', + 'row=row_id, col=col_id, val=value', + 'mat_dense'); +SELECT * FROM mat_dense ORDER BY row_id; +</pre> <pre class="result"> + row_id | value +--------+------------- + 1 | {1,0,0,0,5} + 2 | {0,2,0,6,0} + 3 | {0,7,3,0,0} + 4 | {0,0,8,4,0} +(4 rows) +</pre></li> +<li>Run the PCA sparse function for a specified number of principal components and view the results: <pre class="example">DROP TABLE IF EXISTS result_table, result_table_mean; +SELECT madlib.pca_sparse_train( 'mat_sparse', -- Source table + 'result_table', -- Output table + 'row_id', -- Row id of source table + 'col_id', -- Column id of source table + 'value', -- Value of matrix at row_id, col_id + 4, -- Actual number of rows in the matrix + 5, -- Actual number of columns in the matrix + 3); -- Number of principal components +SELECT * FROM result_table ORDER BY row_id; +</pre> Result (with principal components truncated for readability): <pre class="result"> + row_id | principal_components | std_dev | proportion +--------+----------------------------------------------+------------------+------------------- + 1 | {-0.0876046030186158,-0.0968983772909994,... | 4.21362803829554 | 0.436590030617467 + 2 | {-0.0647272661608605,0.877639526308692,... | 3.68408023747461 | 0.333748701544697 + 3 | {-0.0780380267884855,0.177956517174911,... | 3.05606908060098 | 0.229661267837836 +(3 rows) +</pre></li> +<li>Project the original sparse data to low-dimensional representation: <pre class="example"> +DROP TABLE IF EXISTS mat_sparse_out; +SELECT madlib.pca_sparse_project( + 'mat_sparse', + 'result_table', + 'mat_sparse_out', + 'row_id', + 'col_id', + 'value', + 4, + 5 + ); +SELECT * FROM mat_sparse_out ORDER BY row_id; +</pre> <pre class="result"> + row_id | row_vec +--------+--------------------------------------------------------- + 1 | {4.66617015032369,-2.63552220635847,2.1865220849604} + 2 | {0.228360685652383,-1.21616275892926,-4.46864627611561} + 3 | {0.672067460100428,5.45249627172823,0.56445525585642} + 4 | {-5.5665982960765,-1.6008113064405,1.71766893529879} +(4 rows) +</pre></li> +<li>Now we use grouping in sparse form to learn different models for different groups. First, we create sample data in sparse matrix form with a grouping column: <pre class="example"> +DROP TABLE IF EXISTS mat_sparse_group; +CREATE TABLE mat_sparse_group ( + row_id integer, + col_id integer, + value double precision, + matrix_id integer); +INSERT INTO mat_sparse_group VALUES +(1, 1, 1.0, 1), +(2, 2, 2.0, 1), +(3, 3, 3.0, 1), +(4, 4, 4.0, 1), +(1, 5, 5.0, 1), +(2, 4, 6.0, 2), +(3, 2, 7.0, 2), +(4, 3, 8.0, 2); +</pre></li> +<li>Run the PCA function with grouping for a specified proportion of variance and view the results: <pre class="example"> +DROP TABLE IF EXISTS result_table_group, result_table_group_mean; +SELECT madlib.pca_sparse_train( 'mat_sparse_group', -- Source table + 'result_table_group', -- Output table + 'row_id', -- Row id of source table + 'col_id', -- Column id of source table + 'value', -- Value of matrix at row_id, col_id + 4, -- Actual number of rows in the matrix + 5, -- Actual number of columns in the matrix + 0.8, -- Proportion of variance + 'matrix_id'); +SELECT * FROM result_table_group ORDER BY matrix_id, row_id; +</pre> Result (with principal components truncated for readability): <pre class="result"> + row_id | principal_components | std_dev | proportion | matrix_id +--------+--------------------------------------------+------------------+-------------------+----------- + 1 | {-0.17805696611353,0.0681313257646983,... | 2.73659933165925 | 0.544652792875481 | 1 + 2 | {-0.0492086814863993,0.149371585357526,... | 2.06058314533194 | 0.308800210823714 | 1 + 1 | {0,-0.479486114660443,... | 4.40325305087975 | 0.520500333693473 | 2 + 2 | {0,0.689230898585949,... | 3.7435566458567 | 0.376220573442628 | 2 +(4 rows) +</pre></li> +<li>Projection in sparse format with grouping: <pre class="example"> +DROP TABLE IF EXISTS mat_sparse_group_projected; +SELECT madlib.pca_sparse_project( + 'mat_sparse_group', + 'result_table_group', + 'mat_sparse_group_projected', + 'row_id', + 'col_id', + 'value', + 4, + 5 + ); +SELECT * FROM mat_sparse_group_projected ORDER BY matrix_id, row_id; +</pre> <pre class="result"> + row_id | row_vec | matrix_id +--------+-----------------------------------------+----------- + 1 | {-4.00039298524261,-0.626820612715982} | 1 + 2 | {0.765350785238575,0.951348276645455} | 1 + 3 | {1.04951017256904,2.22388180170356} | 1 + 4 | {2.185532027435,-2.54840946563303} | 1 + 1 | {-0.627846810195469,-0.685031603549092} | 2 + 2 | {-1.64754249747757,-4.7662114622896} | 2 + 3 | {-3.98424961281857,4.13958468655255} | 2 + 4 | {6.25963892049161,1.31165837928614} | 2 +(8 rows) +</pre></li> +</ol> +</dd></dl> +<p><a class="anchor" id="notes"></a></p><dl class="section user"><dt>Notes</dt><dd><ul> +<li>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.</li> +<li>Because of the centering step in PCA projection (see "Technical Background"), 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.</li> +<li>Table names can be optionally schema qualified (current_schemas() is searched if a schema name is not provided) and all table and column names should follow case-sensitivity and quoting rules per the database. (For instance, 'mytable' and 'MyTable' both resolve to the same entity, i.e. 'mytable'. If mixed-case or multi-byte characters are desired for entity names then the string should be double-quoted; in this case the input would be '"MyTable"').</li> +<li>If the input table for pca_project (pca_sparse_project) contains grouping columns, the same grouping columns must be used in the training function used to generate the principal components too.</li> +</ul> +</dd></dl> +<p><a class="anchor" id="background_project"></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> +<p><a class="anchor" id="related"></a></p><dl class="section user"><dt>Related Topics</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></dl> +<p><a class="el" href="group__grp__pca__train.html">Principal Component Analysis</a> </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 Mon Oct 15 2018 11:24:30 for MADlib by + <a href="http://www.doxygen.org/index.html";> + <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.14 </li> + </ul> +</div> +</body> +</html> http://git-wip-us.apache.org/repos/asf/madlib-site/blob/af0e5f14/docs/v1.15.1/group__grp__pca__train.html ---------------------------------------------------------------------- diff --git a/docs/v1.15.1/group__grp__pca__train.html b/docs/v1.15.1/group__grp__pca__train.html new file mode 100644 index 0000000..0678ca3 --- /dev/null +++ b/docs/v1.15.1/group__grp__pca__train.html @@ -0,0 +1,463 @@ +<!-- HTML header for doxygen 1.8.4--> +<!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.14"/> +<meta name="keywords" content="madlib,postgres,greenplum,machine learning,data mining,deep learning,ensemble methods,data science,market basket analysis,affinity analysis,pca,lda,regression,elastic net,huber white,proportional hazards,k-means,latent dirichlet allocation,bayes,support vector machines,svm"/> +<title>MADlib: Principal Component Analysis</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="navtreedata.js"></script> +<script type="text/javascript" src="navtree.js"></script> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ + $(document).ready(initResizable); +/* @license-end */</script> +<link href="search/search.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="search/searchdata.js"></script> +<script type="text/javascript" src="search/search.js"></script> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ + $(document).ready(function() { init_search(); }); +/* @license-end */ +</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 type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js";></script> +<!-- hack in the navigation tree --> +<script type="text/javascript" src="eigen_navtree_hacks.js"></script> +<link href="doxygen.css" rel="stylesheet" type="text/css" /> +<link href="madlib_extra.css" rel="stylesheet" type="text/css"/> +<!-- google analytics --> +<script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + ga('create', 'UA-45382226-1', 'madlib.apache.org'); + ga('send', 'pageview'); +</script> +</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 id="projectlogo"><a href="http://madlib.apache.org";><img alt="Logo" src="madlib.png" height="50" style="padding-left:0.5em;" border="0"/ ></a></td> + <td style="padding-left: 0.5em;"> + <div id="projectname"> + <span id="projectnumber">1.15.1</span> + </div> + <div id="projectbrief">User Documentation for Apache MADlib</div> + </td> + <td> <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> +</td> + </tr> + </tbody> +</table> +</div> +<!-- end header part --> +<!-- Generated by Doxygen 1.8.14 --> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +var searchBox = new SearchBox("searchBox", "search",false,'Search'); +/* @license-end */ +</script> +</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"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +$(document).ready(function(){initNavTree('group__grp__pca__train.html','');}); +/* @license-end */ +</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)"> +</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">Principal Component Analysis<div class="ingroups"><a class="el" href="group__grp__unsupervised.html">Unsupervised Learning</a> » <a class="el" href="group__grp__pca.html">Dimensionality Reduction</a></div></div> </div> +</div><!--header--> +<div class="contents"> +<div class="toc"><b>Contents</b> <ul> +<li class="level1"> +<a href="#train">Training Function</a> </li> +<li class="level1"> +<a href="#examples">Examples</a> </li> +<li class="level1"> +<a href="#notes">Notes</a> </li> +<li class="level1"> +<a href="#background_pca">Technical Background</a> </li> +<li class="level1"> +<a href="#literature">Literature</a> </li> +<li class="level1"> +<a href="#related">Related Topics</a> </li> +</ul> +</div><p>Principal component analysis (PCA) is a mathematical procedure that uses an orthogonal transformation to convert a set of observations of possibly correlated variables into a set of values of linearly uncorrelated variables called principal components. This transformation is defined in such a way that the first principal component has the largest possible variance (i.e., accounts for as much of the variability in the data as possible), and each succeeding component in turn has the highest variance possible under the constraint that it be orthogonal to (i.e., uncorrelated with) the preceding components.</p> +<p>See the <a class="el" href="group__grp__pca__train.html#background_pca">Technical Background</a> for an introduction to principal component analysis.</p> +<p><a class="anchor" id="train"></a></p><dl class="section user"><dt>Training Function</dt><dd>The training functions are slightly different for dense and sparse matrices. For dense matrices: <pre class="syntax"> +pca_train( source_table, + out_table, + row_id, + components_param, + grouping_cols, + lanczos_iter, + use_correlation, + result_summary_table + ) +</pre> For sparse matrices: <pre class="syntax"> +pca_sparse_train( source_table, + out_table, + row_id, + col_id, -- Sparse matrices only + val_id, -- Sparse matrices only + row_dim, -- Sparse matrices only + col_dim, -- Sparse matrices only + components_param, + grouping_cols, + lanczos_iter, + use_correlation, + result_summary_table + ) +</pre></dd></dl> +<p><b>Arguments</b> </p><dl class="arglist"> +<dt>source_table </dt> +<dd><p class="startdd">TEXT. Name of the input table containing the data for PCA training. 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>A dense input table is expected to be in the one of the two standard MADlib dense matrix formats, and a sparse input table should be in the standard MADlib sparse matrix format.</p> +<p>The two standard MADlib dense matrix formats are: </p><pre>{TABLE|VIEW} <em>source_table</em> ( + <em>row_id</em> INTEGER, + <em>row_vec</em> FLOAT8[], +)</pre><p> and </p><pre>{TABLE|VIEW} <em>source_table</em> ( + <em>row_id</em> INTEGER, + <em>col1</em> FLOAT8, + <em>col2</em> FLOAT8, + ... +)</pre><p>Note that the column name <em>row_id</em> is taken as an input parameter, and should contain a continguous list of row indices (starting at 1) for the input matrix.</p> +<p>The input table for sparse PCA is expected to be in the form:</p> +<pre>{TABLE|VIEW} <em>source_table</em> ( + ... + <em>row_id</em> INTEGER, + <em>col_id</em> INTEGER, + <em>val_id</em> FLOAT8, + ... +)</pre><p>The <em>row_id</em> and <em>col_id</em> columns specify which entries in the matrix are nonzero, and the <em>val_id</em> column defines the values of the nonzero entries.</p> +<p>Please refer to the <a class="el" href="group__grp__matrix.html">Matrix Operations</a> documentation for more details on defining matrices. </p> +<p class="enddd"></p> +</dd> +<dt>out_table </dt> +<dd><p class="startdd">TEXT. The name of the table that will contain the output. There are three possible output tables as described below.</p> +<p>The primary output table (<em>out_table</em>) encodes the principal components with the <em>k</em> highest eigenvalues where <em>k</em> is either directly provided by the user or computed according to the proportion of variance. The table has the following columns: </p><table class="output"> +<tr> +<th>row_id </th><td>Eigenvalue rank in descending order of the eigenvalue size. </td></tr> +<tr> +<th>principal_components </th><td>Vectors containing elements of the principal components. </td></tr> +<tr> +<th>std_dev </th><td>The standard deviation of each principal component. </td></tr> +<tr> +<th>proportion </th><td>The proportion of variance covered by the principal component. </td></tr> +</table> +<p>The table <em>out_table_mean</em> contains the column means. This table has just one column: </p><table class="output"> +<tr> +<th>column_mean </th><td>A vector containing the column means for the input matrix. </td></tr> +</table> +<p>The optional table <em>result_summary_table</em> contains information about the performance of the PCA. The contents of this table are described under the <em>result_summary_table</em> argument. </p> +<p class="enddd"></p> +</dd> +<dt>row_id </dt> +<dd><p class="startdd">TEXT. Column name containing the row IDs in the input source table. The column should be of type INT (or a type that can be cast to INT) and should only contain values between 1 and <em>N</em>. For dense matrix format, it should contain all continguous integers from 1 to <em>N</em> describing the full matrix.</p> +<p class="enddd"></p> +</dd> +<dt>col_id </dt> +<dd><p class="startdd">TEXT. Column name containing the column IDs in sparse matrix representation. The column should be of type INT (or a type that can be cast to INT) and should only contain values between 1 and <em>M</em>. <em>This parameter applies to sparse matrices only.</em></p> +<p class="enddd"></p> +</dd> +<dt>val_id </dt> +<dd><p class="startdd">TEXT. Name of 'val_id' column in sparse matrix representation defining the values of the nonzero entries. <em>This parameter applies to sparse matrices only.</em></p> +<p class="enddd"></p> +</dd> +<dt>row_dim </dt> +<dd><p class="startdd">INTEGER. The actual number of rows in the matrix. That is, if the matrix was transformed into dense format, this is the number of rows it would have. <em>This parameter applies to sparse matrices only.</em></p> +<p class="enddd"></p> +</dd> +<dt>col_dim </dt> +<dd><p class="startdd">INTEGER. The actual number of columns in the matrix. That is, if the matrix was transformed into dense format, this is the number of columns it would have. <em>This parameter applies to sparse matrices only.</em></p> +<dl class="section note"><dt>Note</dt><dd>The parameters 'row_dim' and 'col_dim' could actually be inferred from the sparse matrix representation, so they will be removed in the future. For now they are maintained for backward compatability so you must enter them. Making 'row_dim' or 'col_dim' larger than the actual matrix has the effect of padding it with zeros, which is probably not useful.</dd></dl> +</dd> +<dt>components_param </dt> +<dd><p class="startdd">INTEGER or FLOAT. The parameter to control the number of principal components to calculate from the input data. If 'components_param' is INTEGER, it is used to denote the number of principal components (<em>k</em>) to compute. If 'components_param' is FLOAT, the algorithm will return enough principal vectors so that the ratio of the sum of the eigenvalues collected thus far to the sum of all eigenvalues is greater than this parameter (proportion of variance). The value of 'components_param' must be either a positive INTEGER or a FLOAT in the range (0.0,1.0]</p> +<dl class="section note"><dt>Note</dt><dd>The difference in interpretation between INTEGER and FLOAT was introduced to maintain backward campatibility after the proportion of variance feature was introduced. A special case to be aware of: 'components_param' = 1 (INTEGER) will return 1 principal component, but 'components_param' = 1.0 (FLOAT) will return all principal components, i.e., proportion of variance of 100%. <br /> + <br /> +Also, please note that the number of principal components (<em>k</em>) is global, even in the case where grouping is used (see 'grouping_cols' below). In the case of grouping, proportion of variance might be a better choice; this could result in different numbers of principal components for different groups.</dd></dl> +</dd> +<dt>grouping_cols (optional) </dt> +<dd><p class="startdd">TEXT, default: NULL. A comma-separated list of column names, with the source data grouped using the combination of all the columns. An independent PCA model will be computed for each combination of the grouping columns.</p> +<dl class="section note"><dt>Note</dt><dd>Dense matrices can be different sizes for different groups if desired. Sparse matrices cannot be different sizes for different groups, because the 'row_dim' and 'col_dim' parameters used for sparse matrices are global across all groups.</dd></dl> +</dd> +<dt>lanczos_iter (optional) </dt> +<dd><p class="startdd">INTEGER, default: minimum of {<em>k+40</em>, smallest matrix dimension} where <em>k</em> is the number of principal components specified in the parameter 'components_param'. This parameter defines the number of Lanczos iterations for the SVD calculation. The Lanczos iteration number roughly corresponds to the accuracy of the SVD calculation, and a higher number of iterations corresponds to greater accuracy but longer computation time. The number of iterations must be at least as large as the value of <em>k</em>, but no larger than the smallest dimension of the matrix. If the number of iterations is set to zero, then the default number of iterations will be used.</p> +<dl class="section note"><dt>Note</dt><dd>If both 'lanczos_iter' and proportion of variance (via the 'components_param' parameter) are defined, 'lanczos_iter' will take precedence in determining the number of principal components (i.e. the number of principal components will not be greater than 'lanczos_iter' even if the target proportion had not been reached).</dd></dl> +</dd> +<dt>use_correlation (optional) </dt> +<dd><p class="startdd">BOOLEAN, default FALSE. Whether to use the correlation matrix for calculating the principal components instead of the covariance matrix. Currently <em>use_correlation</em> is a placeholder for forward compatibility, so this value must be set to false.</p> +<p class="enddd"></p> +</dd> +<dt>result_summary_table (optional) </dt> +<dd><p class="startdd">TEXT, default NULL. Name of the optional summary table. When NULL, no summary table is generated.</p> +<p class="enddd">This sumary table has the following columns: </p><table class="output"> +<tr> +<th>rows_used </th><td>INTEGER. Number of data points in the input. </td></tr> +<tr> +<th>exec_time (ms) </th><td>FLOAT8. Number of milliseconds for the PCA calculation to run. </td></tr> +<tr> +<th>iter </th><td>INTEGER. Number of iterations used in the SVD calculation. </td></tr> +<tr> +<th>recon_error </th><td>FLOAT8. The absolute error in the SVD approximation. </td></tr> +<tr> +<th>relative_recon_error </th><td>FLOAT8. The relative error in the SVD approximation. </td></tr> +<tr> +<th>use_correlation </th><td>BOOLEAN. Indicates if the correlation matrix was used. </td></tr> +</table> +</dd> +</dl> +<p><a class="anchor" id="examples"></a></p><dl class="section user"><dt>Examples</dt><dd></dd></dl> +<ol type="1"> +<li>View online help for the PCA training functions: <pre class="example"> +SELECT madlib.pca_train(); +or +SELECT madlib.pca_sparse_train(); +</pre></li> +<li>Create sample data in dense matrix form: <pre class="example"> +DROP TABLE IF EXISTS mat; +CREATE TABLE mat (id integer, + row_vec double precision[] + ); +INSERT INTO mat VALUES +(1, '{1,2,3}'), +(2, '{2,1,2}'), +(3, '{3,2,1}'); +</pre></li> +<li>Run the PCA function for a specified number of principal components and view the results: <pre class="example"> +DROP TABLE IF EXISTS result_table, result_table_mean; +SELECT madlib.pca_train('mat', -- Source table + 'result_table', -- Output table + 'id', -- Row id of source table + 2); -- Number of principal components +SELECT * FROM result_table ORDER BY row_id; +</pre> <pre class="result"> + row_id | principal_components | std_dev | proportion +--------+--------------------------------------------------------------+-------------------+------------------- + 1 | {0.707106781186547,-6.93889390390723e-18,-0.707106781186548} | 1.41421356237309 | 0.857142857142244 + 2 | {0,1,0} | 0.577350269189626 | 0.142857142857041 +(2 rows) +</pre></li> +<li>Run the PCA function for a specified proportion of variance and view the results: <pre class="example"> +%sql +DROP TABLE IF EXISTS result_table, result_table_mean; +SELECT madlib.pca_train('mat', -- Source table + 'result_table', -- Output table + 'id', -- Row id of source table + 0.9); -- Proportion of variance +SELECT * FROM result_table ORDER BY row_id; +</pre> <pre class="result"> + row_id | principal_components | std_dev | proportion +--------+--------------------------------------------------------------+-------------------+------------------- + 1 | {0.707106781186548,-2.77555756156289e-17,-0.707106781186548} | 1.4142135623731 | 0.857142857142245 + 2 | {-1.11022302462516e-16,-1,0} | 0.577350269189626 | 0.142857142857041 +(2 rows) +</pre></li> +<li>Now we use grouping in dense form to learn different models for different groups. First, we create sample data in dense matrix form with a grouping column. Note we actually have different matrix sizes for the different groups, which is allowed for dense: <pre class="example"> +DROP TABLE IF EXISTS mat_group; +CREATE TABLE mat_group ( + id integer, + row_vec double precision[], + matrix_id integer +); +INSERT INTO mat_group VALUES +(1, '{1,2,3}', 1), +(2, '{2,1,2}', 1), +(3, '{3,2,1}', 1), +(4, '{1,2,3,4,5}', 2), +(5, '{2,5,2,4,1}', 2), +(6, '{5,4,3,2,1}', 2); +</pre></li> +<li>Run the PCA function with grouping for a specified proportion of variance and view the results: <pre class="example"> +DROP TABLE IF EXISTS result_table_group, result_table_group_mean; +SELECT madlib.pca_train('mat_group', -- Source table + 'result_table_group', -- Output table + 'id', -- Row id of source table + 0.8, -- Proportion of variance + 'matrix_id'); -- Grouping column +SELECT * FROM result_table_group ORDER BY matrix_id, row_id; +</pre> <pre class="result"> + row_id | principal_components | std_dev | proportion | matrix_id +--------+------------------------------------------------------------------------------------------------+-----------------+-------------------+----------- + 1 | {0.707106781186548,0,-0.707106781186547} | 1.4142135623731 | 0.857142857142245 | 1 + 1 | {-0.555378486712784,-0.388303582074091,0.0442457354870796,0.255566375612852,0.688115693174023} | 3.2315220311722 | 0.764102534485173 | 2 + 2 | {0.587384101786277,-0.485138064894743,0.311532046315153,-0.449458074050715,0.347212037159181} | 1.795531127192 | 0.235897465516047 | 2 +(3 rows) +</pre></li> +<li>Now let's look at sparse matrices. Create sample data in sparse matrix form: <pre class="example"> +DROP TABLE IF EXISTS mat_sparse; +CREATE TABLE mat_sparse ( + row_id integer, + col_id integer, + value double precision +); +INSERT INTO mat_sparse VALUES +(1, 1, 1.0), +(2, 2, 2.0), +(3, 3, 3.0), +(4, 4, 4.0), +(1, 5, 5.0), +(2, 4, 6.0), +(3, 2, 7.0), +(4, 3, 8.0); +</pre> As an aside, this is what the sparse matrix above looks like when put in dense form: <pre class="example"> +DROP TABLE IF EXISTS mat_dense; +SELECT madlib.matrix_densify('mat_sparse', + 'row=row_id, col=col_id, val=value', + 'mat_dense'); +SELECT * FROM mat_dense ORDER BY row_id; +</pre> <pre class="result"> + row_id | value +--------+------------- + 1 | {1,0,0,0,5} + 2 | {0,2,0,6,0} + 3 | {0,7,3,0,0} + 4 | {0,0,8,4,0} +(4 rows) +</pre></li> +<li>Run the PCA sparse function for a specified number of principal components and view the results: <pre class="example">DROP TABLE IF EXISTS result_table, result_table_mean; +SELECT madlib.pca_sparse_train( 'mat_sparse', -- Source table + 'result_table', -- Output table + 'row_id', -- Row id of source table + 'col_id', -- Column id of source table + 'value', -- Value of matrix at row_id, col_id + 4, -- Actual number of rows in the matrix + 5, -- Actual number of columns in the matrix + 3); -- Number of principal components +SELECT * FROM result_table ORDER BY row_id; +</pre> Result (with principal components truncated for readability): <pre class="result"> + row_id | principal_components | std_dev | proportion +--------+----------------------------------------------+------------------+------------------- + 1 | {-0.0876046030186158,-0.0968983772909994,... | 4.21362803829554 | 0.436590030617467 + 2 | {-0.0647272661608605,0.877639526308692,... | 3.68408023747461 | 0.333748701544697 + 3 | {-0.0780380267884855,0.177956517174911,... | 3.05606908060098 | 0.229661267837836 +(3 rows) +</pre></li> +<li>Now we use grouping in sparse form to learn different models for different groups. First, we create sample data in sparse matrix form with a grouping column: <pre class="example"> +DROP TABLE IF EXISTS mat_sparse_group; +CREATE TABLE mat_sparse_group ( + row_id integer, + col_id integer, + value double precision, + matrix_id integer); +INSERT INTO mat_sparse_group VALUES +(1, 1, 1.0, 1), +(2, 2, 2.0, 1), +(3, 3, 3.0, 1), +(4, 4, 4.0, 1), +(1, 5, 5.0, 1), +(2, 4, 6.0, 2), +(3, 2, 7.0, 2), +(4, 3, 8.0, 2); +</pre></li> +<li>Run the PCA function with grouping for a specified proportion of variance and view the results: <pre class="example"> +DROP TABLE IF EXISTS result_table_group, result_table_group_mean; +SELECT madlib.pca_sparse_train( 'mat_sparse_group', -- Source table + 'result_table_group', -- Output table + 'row_id', -- Row id of source table + 'col_id', -- Column id of source table + 'value', -- Value of matrix at row_id, col_id + 4, -- Actual number of rows in the matrix + 5, -- Actual number of columns in the matrix + 0.8, -- Proportion of variance + 'matrix_id'); +SELECT * FROM result_table_group ORDER BY matrix_id, row_id; +</pre> Result (with principal components truncated for readability): <pre class="result"> + row_id | principal_components | std_dev | proportion | matrix_id +--------+--------------------------------------------+------------------+-------------------+----------- + 1 | {-0.17805696611353,0.0681313257646983,... | 2.73659933165925 | 0.544652792875481 | 1 + 2 | {-0.0492086814863993,0.149371585357526,... | 2.06058314533194 | 0.308800210823714 | 1 + 1 | {0,-0.479486114660443,... | 4.40325305087975 | 0.520500333693473 | 2 + 2 | {0,0.689230898585949,... | 3.7435566458567 | 0.376220573442628 | 2 +(4 rows) +</pre></li> +</ol> +<p><a class="anchor" id="notes"></a></p><dl class="section user"><dt>Notes</dt><dd></dd></dl> +<ul> +<li>Table names can be optionally schema qualified (current_schemas() would be searched if a schema name is not provided) and all table and column names should follow case-sensitivity and quoting rules per the database. (For instance, 'mytable' and 'MyTable' both resolve to the same entity, i.e. 'mytable'. If mixed-case or multi-byte characters are desired for entity names then the string should be double-quoted; in this case the input would be '"MyTable"').</li> +<li>Because of the centering step in PCA (see <a class="el" href="group__grp__pca__train.html#background_pca">Technical Background</a>), sparse matrices almost always become dense during the training process. Since this implementation automatically densifies sparse matrix input, there should be no expected performance improvement in using sparse matrix input over dense matrix input.</li> +<li>For the parameter 'components_param', INTEGER and FLOAT are interpreted differently. A special case to be aware of: 'components_param' = 1 (INTEGER) will return 1 principal component, but 'components_param' = 1.0 (FLOAT) will return all principal components, i.e., proportion of variance of 100%.</li> +<li>If both 'lanczos_iter' and proportion of variance (via the 'components_param' parameter) are defined, 'lanczos_iter' will take precedence in determining the number of principal components (i.e. the number of principal components will not be greater than 'lanczos_iter' even if the target proportion had not been reached).</li> +</ul> +<p><a class="anchor" id="background_pca"></a></p><dl class="section user"><dt>Technical Background</dt><dd></dd></dl> +<p>The PCA implemented here uses a distributed SVD decomposition implementation to recover the principal components (as opposed to the directly computing the eigenvectors of the covariance matrix). Let \( \boldsymbol X \) be the data matrix, and let \( \hat{x} \) be a vector of the column averages of \( \boldsymbol{X}\). PCA computes the matrix \( \hat{\boldsymbol X} \) as </p><p class="formulaDsp"> +\[ \hat{\boldsymbol X} = {\boldsymbol X} - \vec{e} \hat{x}^T \] +</p> +<p> where \( \vec{e} \) is the vector of all ones.</p> +<p>PCA then computes the SVD matrix factorization </p><p class="formulaDsp"> +\[ \hat{\boldsymbol X} = {\boldsymbol U}{\boldsymbol \Sigma}{\boldsymbol V}^T \] +</p> +<p> where \( {\boldsymbol \Sigma} \) is a diagonal matrix. The eigenvalues are recovered as the entries of \( {\boldsymbol \Sigma}/(\sqrt{(N-1)} \), and the principal components are the rows of \( {\boldsymbol V} \). The reasoning behind using N â 1 instead of N to calculate the covariance is <a href="https://en.wikipedia.org/wiki/Bessel%27s_correction";>Bessel's correction</a>.</p> +<dl class="section note"><dt>Note</dt><dd>It is important to note that this PCA implementation assumes that the user will use only the principal components that have non-zero eigenvalues. The SVD calculation is done with the Lanczos method, which does not guarantee correctness for singular vectors with zero-valued eigenvalues. Consequently, principal components with zero-valued eigenvalues are not guaranteed to be correct. Generally, this will not be problem unless the user wants to use the principal components for the entire eigenspectrum.</dd></dl> +<p><a class="anchor" id="literature"></a></p><dl class="section user"><dt>Literature</dt><dd></dd></dl> +<p>[1] Principal Component Analysis. <a href="http://en.wikipedia.org/wiki/Principal_component_analysis";>http://en.wikipedia.org/wiki/Principal_component_analysis</a></p> +<p>[2] Shlens, Jonathon (2009), A Tutorial on Principal Component Analysis</p> +<p><a class="anchor" id="related"></a></p><dl class="section user"><dt>Related Topics</dt><dd></dd></dl> +<p>File <a class="el" href="pca_8sql__in.html" title="Principal Component Analysis. ">pca.sql_in</a> documenting the SQL functions</p> +<p><a class="el" href="group__grp__pca__project.html">Principal Component Projection</a> </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 Mon Oct 15 2018 11:24:30 for MADlib by + <a href="http://www.doxygen.org/index.html";> + <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.14 </li> + </ul> +</div> +</body> +</html>
