Standardized docstrings comments, added type hints

README.md

@@ -45,6 +45,7 @@ See main.py for examples and read the documentation.
 - more clustering algorithms (mountain clustering, subtractive clustering)
 - preprocessing functions for matrix data (center and scale, e.g., z-scores)
 - labeled matrices
+- example data analysis project to showcase existing features
 
 ## License
 

mola.clustering.html

@@ -25,18 +25,18 @@
 <font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr>
 
 <tr><td bgcolor="#eeaa77"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
-<td width="100%"><dl><dt><a name="-distance_euclidean_pow"><strong>distance_euclidean_pow</strong></a>(p1, p2)</dt><dd><tt>Return&nbsp;the&nbsp;squared&nbsp;Euclidean&nbsp;distance&nbsp;between&nbsp;two&nbsp;points.<br>
+<td width="100%"><dl><dt><a name="-distance_euclidean_pow"><strong>distance_euclidean_pow</strong></a>(p1, p2) -&gt; float</dt><dd><tt>Return&nbsp;the&nbsp;squared&nbsp;Euclidean&nbsp;distance&nbsp;between&nbsp;two&nbsp;points.<br>
 If&nbsp;you&nbsp;want&nbsp;to&nbsp;retrieve&nbsp;the&nbsp;actual&nbsp;Euclidean&nbsp;distance,&nbsp;take&nbsp;the&nbsp;square&nbsp;root&nbsp;of&nbsp;the&nbsp;result.&nbsp;However,&nbsp;using&nbsp;this&nbsp;squared&nbsp;version&nbsp;is&nbsp;computationally&nbsp;more&nbsp;efficient.<br>
 &nbsp;<br>
 Arguments:<br>
 p1&nbsp;--&nbsp;list:&nbsp;the&nbsp;first&nbsp;point<br>
 p2&nbsp;--&nbsp;list:&nbsp;the&nbsp;second&nbsp;point</tt></dd></dl>
- <dl><dt><a name="-distance_taxicab"><strong>distance_taxicab</strong></a>(p1, p2)</dt><dd><tt>Return&nbsp;the&nbsp;taxicab&nbsp;distance&nbsp;(also&nbsp;known&nbsp;as&nbsp;Manhattan&nbsp;distance)&nbsp;between&nbsp;two&nbsp;points.<br>
+ <dl><dt><a name="-distance_taxicab"><strong>distance_taxicab</strong></a>(p1, p2) -&gt; float</dt><dd><tt>Return&nbsp;the&nbsp;taxicab&nbsp;distance&nbsp;(also&nbsp;known&nbsp;as&nbsp;Manhattan&nbsp;distance)&nbsp;between&nbsp;two&nbsp;points.<br>
 &nbsp;<br>
 Arguments:<br>
 p1&nbsp;--&nbsp;list:&nbsp;the&nbsp;first&nbsp;point<br>
 p2&nbsp;--&nbsp;list:&nbsp;the&nbsp;second&nbsp;point</tt></dd></dl>
- <dl><dt><a name="-find_c_means"><strong>find_c_means</strong></a>(data, num_centers=2, max_iterations=100, distance_function=&lt;function distance_euclidean_pow at 0x000002575B236E50&gt;, initial_centers=None)</dt><dd><tt>Return&nbsp;the&nbsp;cluster&nbsp;centers&nbsp;and&nbsp;the&nbsp;membership&nbsp;matrix&nbsp;of&nbsp;points&nbsp;using&nbsp;soft&nbsp;k-means&nbsp;clustering&nbsp;(also&nbsp;known&nbsp;as&nbsp;fuzzy&nbsp;c-means).<br>
+ <dl><dt><a name="-find_c_means"><strong>find_c_means</strong></a>(data: mola.matrix.Matrix, num_centers=2, max_iterations=100, distance_function=&lt;function distance_euclidean_pow at 0x00000256295E9550&gt;, initial_centers=None)</dt><dd><tt>Return&nbsp;the&nbsp;cluster&nbsp;centers&nbsp;and&nbsp;the&nbsp;membership&nbsp;matrix&nbsp;of&nbsp;points&nbsp;using&nbsp;soft&nbsp;k-means&nbsp;clustering&nbsp;(also&nbsp;known&nbsp;as&nbsp;fuzzy&nbsp;c-means).<br>
 &nbsp;<br>
 This&nbsp;algorithm&nbsp;is&nbsp;well-suited&nbsp;to&nbsp;cluster&nbsp;data&nbsp;that&nbsp;is&nbsp;not&nbsp;clearly&nbsp;separable&nbsp;into&nbsp;distinct&nbsp;clusters.<br>
 &nbsp;&nbsp;&nbsp;&nbsp;<br>
@@ -46,7 +46,7 @@
 max_iterations&nbsp;--&nbsp;int:&nbsp;the&nbsp;maximum&nbsp;number&nbsp;of&nbsp;iterations&nbsp;where&nbsp;cluster&nbsp;centers&nbsp;are&nbsp;updated&nbsp;(default&nbsp;100)<br>
 distance_function&nbsp;--&nbsp;function:&nbsp;the&nbsp;distance&nbsp;function&nbsp;to&nbsp;be&nbsp;used&nbsp;(default&nbsp;Euclidean&nbsp;distance);&nbsp;options&nbsp;are&nbsp;squared&nbsp;Euclidean&nbsp;distance&nbsp;(distance_euclidean_pow)&nbsp;and&nbsp;taxicab&nbsp;distance&nbsp;(distance_taxicab)<br>
 initial_centers&nbsp;--&nbsp;Matrix:&nbsp;the&nbsp;initial&nbsp;cluster&nbsp;centers;&nbsp;if&nbsp;not&nbsp;specified,&nbsp;they&nbsp;are&nbsp;initialized&nbsp;randomly&nbsp;(default&nbsp;None)</tt></dd></dl>
- <dl><dt><a name="-find_k_means"><strong>find_k_means</strong></a>(data, num_centers=2, max_iterations=100, distance_function=&lt;function distance_euclidean_pow at 0x000002575B236E50&gt;, initial_centers=None)</dt><dd><tt>Return&nbsp;the&nbsp;cluster&nbsp;centers&nbsp;using&nbsp;hard&nbsp;k-means&nbsp;clustering.<br>
+ <dl><dt><a name="-find_k_means"><strong>find_k_means</strong></a>(data: mola.matrix.Matrix, num_centers=2, max_iterations=100, distance_function=&lt;function distance_euclidean_pow at 0x00000256295E9550&gt;, initial_centers=None)</dt><dd><tt>Return&nbsp;the&nbsp;cluster&nbsp;centers&nbsp;using&nbsp;hard&nbsp;k-means&nbsp;clustering.<br>
 &nbsp;<br>
 Note&nbsp;that&nbsp;there&nbsp;is&nbsp;no&nbsp;guarantee&nbsp;that&nbsp;the&nbsp;algorithm&nbsp;converges.&nbsp;This&nbsp;is&nbsp;why&nbsp;you&nbsp;should&nbsp;use&nbsp;several&nbsp;restarts&nbsp;or&nbsp;fuzzy&nbsp;k-means&nbsp;(function&nbsp;<a href="#-find_c_means">find_c_means</a>()&nbsp;in&nbsp;this&nbsp;module).<br>
 &nbsp;<br>

mola.decomposition.html

@@ -25,20 +25,33 @@
 <font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr>
 
 <tr><td bgcolor="#eeaa77"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
-<td width="100%"><dl><dt><a name="-eigend"><strong>eigend</strong></a>(S)</dt><dd><tt>Calculate&nbsp;the&nbsp;eigenvalue&nbsp;decomposition&nbsp;of&nbsp;matrix&nbsp;S&nbsp;and&nbsp;return&nbsp;the&nbsp;matrix&nbsp;of&nbsp;eigenvalues&nbsp;E&nbsp;and&nbsp;matrix&nbsp;of&nbsp;eigenvectors&nbsp;V.<br>
+<td width="100%"><dl><dt><a name="-eigend"><strong>eigend</strong></a>(S: mola.matrix.Matrix)</dt><dd><tt>Calculate&nbsp;the&nbsp;eigenvalue&nbsp;decomposition&nbsp;of&nbsp;matrix&nbsp;S&nbsp;and&nbsp;return&nbsp;the&nbsp;matrix&nbsp;of&nbsp;eigenvalues&nbsp;E&nbsp;and&nbsp;matrix&nbsp;of&nbsp;eigenvectors&nbsp;V.<br>
 Uses&nbsp;the&nbsp;Jacobi&nbsp;eigendecomposition&nbsp;algorithm.<br>
 &nbsp;<br>
+Arguments:<br>
+S&nbsp;--&nbsp;Matrix:&nbsp;the&nbsp;matrix&nbsp;whose&nbsp;eigenvalue&nbsp;decomposition&nbsp;is&nbsp;to&nbsp;be&nbsp;calculated<br>
+&nbsp;<br>
 Raises&nbsp;an&nbsp;exception&nbsp;if&nbsp;the&nbsp;matrix&nbsp;is&nbsp;not&nbsp;symmetric&nbsp;(for&nbsp;now).</tt></dd></dl>
- <dl><dt><a name="-eigenvector"><strong>eigenvector</strong></a>(A)</dt><dd><tt>Return&nbsp;the&nbsp;dominant&nbsp;eigenvector&nbsp;and&nbsp;corresponding&nbsp;eigenvalue&nbsp;of&nbsp;matrix&nbsp;A.</tt></dd></dl>
- <dl><dt><a name="-power_method"><strong>power_method</strong></a>(A)</dt><dd><tt>Return&nbsp;the&nbsp;dominant&nbsp;eigenvalue&nbsp;of&nbsp;the&nbsp;matrix&nbsp;A.</tt></dd></dl>
- <dl><dt><a name="-qrd"><strong>qrd</strong></a>(A_original)</dt><dd><tt>Return&nbsp;a&nbsp;two-element&nbsp;tuple&nbsp;of&nbsp;matrices.<br>
+ <dl><dt><a name="-eigenvector"><strong>eigenvector</strong></a>(A: mola.matrix.Matrix) -&gt; tuple</dt><dd><tt>Return&nbsp;the&nbsp;dominant&nbsp;eigenvector&nbsp;and&nbsp;corresponding&nbsp;eigenvalue&nbsp;of&nbsp;matrix&nbsp;A.</tt></dd></dl>
+ <dl><dt><a name="-power_method"><strong>power_method</strong></a>(A: mola.matrix.Matrix) -&gt; mola.matrix.Matrix</dt><dd><tt>Return&nbsp;the&nbsp;dominant&nbsp;eigenvector&nbsp;of&nbsp;the&nbsp;matrix&nbsp;A.<br>
+&nbsp;<br>
+Arguments:<br>
+A&nbsp;--&nbsp;Matrix:&nbsp;the&nbsp;matrix&nbsp;whose&nbsp;dominant&nbsp;eigenvector&nbsp;is&nbsp;to&nbsp;be&nbsp;calculated</tt></dd></dl>
+ <dl><dt><a name="-qrd"><strong>qrd</strong></a>(A_original: mola.matrix.Matrix)</dt><dd><tt>Return&nbsp;a&nbsp;two-element&nbsp;tuple&nbsp;of&nbsp;matrices.<br>
 The&nbsp;elements&nbsp;of&nbsp;the&nbsp;tuple&nbsp;are&nbsp;the&nbsp;Q&nbsp;and&nbsp;R&nbsp;matrices&nbsp;from&nbsp;the&nbsp;QR&nbsp;decomposition&nbsp;of&nbsp;the&nbsp;input&nbsp;matrix.<br>
 The&nbsp;original&nbsp;input&nbsp;matrix&nbsp;is&nbsp;decomposed&nbsp;into&nbsp;a&nbsp;rotation&nbsp;matrix&nbsp;Q&nbsp;and&nbsp;an&nbsp;upper&nbsp;triangular&nbsp;matrix&nbsp;R.<br>
 The&nbsp;decomposition&nbsp;is&nbsp;valid&nbsp;for&nbsp;any&nbsp;real&nbsp;square&nbsp;matrix.<br>
 &nbsp;<br>
+Arguments:<br>
+A_original&nbsp;--&nbsp;Matrix:&nbsp;the&nbsp;matrix&nbsp;to&nbsp;be&nbsp;decomposed<br>
+&nbsp;<br>
 Raises&nbsp;an&nbsp;exception&nbsp;if&nbsp;the&nbsp;matrix&nbsp;is&nbsp;not&nbsp;square.</tt></dd></dl>
  <dl><dt><a name="-random"><strong>random</strong></a>()<font color="#909090"><font face="helvetica, arial"> method of <a href="random.html#Random">random.Random</a> instance</font></font></dt><dd><tt><a href="#-random">random</a>()&nbsp;-&gt;&nbsp;x&nbsp;in&nbsp;the&nbsp;interval&nbsp;[0,&nbsp;1).</tt></dd></dl>
- <dl><dt><a name="-rayleigh_quotient"><strong>rayleigh_quotient</strong></a>(A, v)</dt><dd><tt>Return&nbsp;the&nbsp;Rayleigh&nbsp;quotient&nbsp;of&nbsp;matrix&nbsp;A.<br>
-The&nbsp;Rayleigh&nbsp;quotient&nbsp;in&nbsp;this&nbsp;case&nbsp;is&nbsp;the&nbsp;eigenvalue&nbsp;corresponding&nbsp;to&nbsp;the&nbsp;eigenvector&nbsp;v.</tt></dd></dl>
+ <dl><dt><a name="-rayleigh_quotient"><strong>rayleigh_quotient</strong></a>(A: mola.matrix.Matrix, v: mola.matrix.Matrix)</dt><dd><tt>Return&nbsp;the&nbsp;Rayleigh&nbsp;quotient&nbsp;of&nbsp;matrix&nbsp;A.<br>
+The&nbsp;Rayleigh&nbsp;quotient&nbsp;in&nbsp;this&nbsp;case&nbsp;is&nbsp;the&nbsp;eigenvalue&nbsp;corresponding&nbsp;to&nbsp;the&nbsp;eigenvector&nbsp;v.<br>
+&nbsp;<br>
+Arguments:<br>
+A&nbsp;--&nbsp;Matrix:&nbsp;the&nbsp;matrix&nbsp;whose&nbsp;Rayleigh&nbsp;quotient&nbsp;is&nbsp;to&nbsp;be&nbsp;calculated<br>
+v&nbsp;--&nbsp;Matrix:&nbsp;the&nbsp;eigenvector&nbsp;corresponding&nbsp;to&nbsp;the&nbsp;eigenvalue&nbsp;to&nbsp;be&nbsp;calculated</tt></dd></dl>
 </td></tr></table>
 </body></html>