Update array-like docstring style (always manually)

aaanalysis/_utils/_decorators.py

@@ -5,7 +5,7 @@
 import traceback
 from sklearn.exceptions import ConvergenceWarning
 import functools
-
+from functools import wraps
 
 # Catch Runtime
 class CatchRuntimeWarnings:
@@ -36,6 +36,7 @@ def get_warnings(self):
         return self._warn_list
 
 def catch_runtime_warnings(func):
+    @wraps(func)
     def wrapper(*args, **kwargs):
         with CatchRuntimeWarnings() as crw:
             result = func(*args, **kwargs)
@@ -55,6 +56,7 @@ def __init__(self, message, distinct_clusters):
         self.distinct_clusters = distinct_clusters
 
 def catch_convergence_warning(func):
+    @wraps(func)
     def wrapper(*args, **kwargs):
         with warnings.catch_warnings(record=True) as w:
             # Trigger the "always" behavior for ConvergenceWarning

aaanalysis/aaclust/aaclust.py

@@ -187,7 +187,7 @@ def fit(self,
         clusters by maximizing the within-cluster Pearson correlation beyond the ``min_th`` threshold. The quality of
         clustering is either based on the minimum Pearson correlation of all members (``on_center=False``) or between
         the cluster center and its members (``on_center=True``), using either the 'min_cor_all' or 'min_cor_center'
-         function, respectively, as described in [Breimann23a]_.
+        function, respectively, as described in [Breimann23a]_.
 
         Parameters
         ----------

docs/build/html/generated/aaanalysis.AAclust.html

@@ -295,8 +295,8 @@ <h1>aaanalysis.AAclust<a class="headerlink" href="#aaanalysis-aaclust" title="Pe
 <tr class="row-even"><td><p><a class="reference internal" href="#aaanalysis.AAclust.eval" title="aaanalysis.AAclust.eval"><code class="xref py py-obj docutils literal notranslate"><span class="pre">eval</span></code></a>(X[, labels])</p></td>
 <td><p>Evaluates the quality of clustering using three established measures.</p></td>
 </tr>
-<tr class="row-odd"><td><p><a class="reference internal" href="#aaanalysis.AAclust.fit" title="aaanalysis.AAclust.fit"><code class="xref py py-obj docutils literal notranslate"><span class="pre">fit</span></code></a>(**kwargs)</p></td>
-<td><p>Fit the model with data.</p></td>
+<tr class="row-odd"><td><p><a class="reference internal" href="#aaanalysis.AAclust.fit" title="aaanalysis.AAclust.fit"><code class="xref py py-obj docutils literal notranslate"><span class="pre">fit</span></code></a>(X[, n_clusters, on_center, min_th, ...])</p></td>
+<td><p>Applies AAclust algorithm to feature matrix (<code class="docutils literal notranslate"><span class="pre">X</span></code>).</p></td>
 </tr>
 <tr class="row-even"><td><p><a class="reference internal" href="#aaanalysis.AAclust.name_clusters" title="aaanalysis.AAclust.name_clusters"><code class="xref py py-obj docutils literal notranslate"><span class="pre">name_clusters</span></code></a>(X[, labels, names])</p></td>
 <td><p>Assigns names to clusters based on the frequency of names.</p></td>
@@ -305,8 +305,69 @@ <h1>aaanalysis.AAclust<a class="headerlink" href="#aaanalysis-aaclust" title="Pe
 </table>
 <dl class="py method">
 <dt class="sig sig-object py" id="aaanalysis.AAclust.fit">
-<span class="sig-name descname"><span class="pre">fit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/breimanntools/aaanalysis/tree/master/aaanalysis/_utils/_decorators.py#L39-L47"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#aaanalysis.AAclust.fit" title="Permalink to this definition"></a></dt>
-<dd><p>Fit the model with data.</p>
+<span class="sig-name descname"><span class="pre">fit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">X</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">n_clusters</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">on_center</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">min_th</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">merge_metric</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'euclidean'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">names</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/breimanntools/aaanalysis/tree/master/aaanalysis/_utils/_decorators.py#L175-L284"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#aaanalysis.AAclust.fit" title="Permalink to this definition"></a></dt>
+<dd><p>Applies AAclust algorithm to feature matrix (<code class="docutils literal notranslate"><span class="pre">X</span></code>).</p>
+<p>AAclust determines the optimal number of clusters, k, without pre-specification. It partitions data (<code class="docutils literal notranslate"><span class="pre">X</span></code>) into
+clusters by maximizing the within-cluster Pearson correlation beyond the <code class="docutils literal notranslate"><span class="pre">min_th</span></code> threshold. The quality of
+clustering is either based on the minimum Pearson correlation of all members (<code class="docutils literal notranslate"><span class="pre">on_center=False</span></code>) or between
+the cluster center and its members (<code class="docutils literal notranslate"><span class="pre">on_center=True</span></code>), using either the ‘min_cor_all’ or ‘min_cor_center’
+function, respectively, as described in <a class="reference internal" href="../index/references.html#breimann23a" id="id2"><span>[Breimann23a]</span></a>.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters<span class="colon">:</span></dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>X</strong> (<cite>array-like, shape (n_samples, n_features)</cite>) – Feature matrix. Rows correspond to scales and columns to amino acids.</p></li>
+<li><p><strong>n_clusters</strong> (<a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Optional" title="(in Python v3.11)"><code class="xref py py-data docutils literal notranslate"><span class="pre">Optional</span></code></a>[<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.11)"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>]) – Pre-defined number of clusters. If provided, k is not optimized. Must be 0 &gt; n_clusters &gt; n_samples.</p></li>
+<li><p><strong>min_th</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.11)"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>) – Pearson correlation threshold for clustering (between 0 and 1).</p></li>
+<li><p><strong>on_center</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.11)"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a>) – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, <code class="docutils literal notranslate"><span class="pre">min_th</span></code> is applied to the cluster center. Otherwise, to all cluster members.</p></li>
+<li><p><strong>merge_metric</strong> (<a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Optional" title="(in Python v3.11)"><code class="xref py py-data docutils literal notranslate"><span class="pre">Optional</span></code></a>[<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>]) – <p>Metric used as similarity measure for optional cluster merging:</p>
+<blockquote>
+<div><ul>
+<li><p><code class="docutils literal notranslate"><span class="pre">None</span></code>: No merging is performed</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">correlation</span></code>: Pearson correlation</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">euclidean</span></code>: Euclidean distance</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">manhattan</span></code>: Manhattan distance</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">cosine</span></code>: Cosine distance</p></li>
+</ul>
+</div></blockquote>
+</p></li>
+<li><p><strong>names</strong> (<a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Optional" title="(in Python v3.11)"><code class="xref py py-data docutils literal notranslate"><span class="pre">Optional</span></code></a>[<a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.List" title="(in Python v3.11)"><code class="xref py py-class docutils literal notranslate"><span class="pre">List</span></code></a>[<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>]]) – Sample names. If provided, sets <a class="reference internal" href="#aaanalysis.AAclust.medoid_names_" title="aaanalysis.AAclust.medoid_names_"><code class="xref py py-attr docutils literal notranslate"><span class="pre">AAclust.medoid_names_</span></code></a> attribute.</p></li>
+</ul>
+</dd>
+<dt class="field-even">Returns<span class="colon">:</span></dt>
+<dd class="field-even"><p>The fitted instance of the AAclust class, allowing direct attribute access.</p>
+</dd>
+<dt class="field-odd">Return type<span class="colon">:</span></dt>
+<dd class="field-odd"><p><a class="reference internal" href="#aaanalysis.AAclust" title="aaanalysis.AAclust">AAclust</a></p>
+</dd>
+</dl>
+<div class="admonition-notes admonition">
+<p class="admonition-title">Notes</p>
+<ul class="simple">
+<li><p>Sets all attributes of the <code class="xref py py-class docutils literal notranslate"><span class="pre">aanalysis.AAclust</span></code> class.</p></li>
+<li><dl class="simple">
+<dt>The AAclust algorithm consists of three main steps:</dt><dd><ol class="arabic simple">
+<li><p>Estimate the lower bound of k.</p></li>
+<li><p>Refine k (recursively) using the chosen quality metric.</p></li>
+<li><p>Optionally, merge smaller clusters as directed by the <code class="docutils literal notranslate"><span class="pre">merge_metric</span></code>.</p></li>
+</ol>
+</dd>
+</dl>
+</li>
+<li><p>A representative scale (medoid) closest to each cluster center is selected for redundancy reduction.</p></li>
+</ul>
+</div>
+<div class="admonition seealso">
+<p class="admonition-title">See also</p>
+<ul class="simple">
+<li><p><a class="reference external" href="https://scikit-learn.org/stable/modules/generated/sklearn.metrics.pairwise_distances.html#sklearn.metrics.pairwise_distances" title="(in scikit-learn v1.3)"><code class="xref py py-func docutils literal notranslate"><span class="pre">sklearn.metrics.pairwise_distances()</span></code></a> were used as distances for merging.</p></li>
+</ul>
+</div>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<ul class="simple">
+<li><p>All RuntimeWarnings during the AAclust algorithm are caught and bundled into one RuntimeWarning.</p></li>
+</ul>
+</div>
 </dd></dl>
 
 <dl class="py method">
@@ -328,7 +389,7 @@ <h1>aaanalysis.AAclust<a class="headerlink" href="#aaanalysis-aaclust" title="Pe
 <dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
 <dd class="field-odd"><ul class="simple">
-<li><p><strong>X</strong> (<cite>array-like, shape (n_samples, n_features)</cite>) – Feature matrix.</p></li>
+<li><p><strong>X</strong> (<cite>array-like, shape (n_samples, n_features)</cite>) – Feature matrix. Rows correspond to scales and columns to amino acids.</p></li>
 <li><p><strong>labels</strong> (<cite>array-like, shape (n_samples, )</cite>) – Cluster labels for each sample in <code class="docutils literal notranslate"><span class="pre">X</span></code>.</p></li>
 </ul>
 </dd>
@@ -344,7 +405,7 @@ <h1>aaanalysis.AAclust<a class="headerlink" href="#aaanalysis-aaclust" title="Pe
 <div class="admonition-notes admonition">
 <p class="admonition-title">Notes</p>
 <p>BIC was modified to align with the SC and CH, so that higher values signify better clustering
-contrary to conventional BIC implementation favoring lower values. See <a class="reference internal" href="../index/references.html#breimann23a" id="id2"><span>[Breimann23a]</span></a>.</p>
+contrary to conventional BIC implementation favoring lower values. See <a class="reference internal" href="../index/references.html#breimann23a" id="id3"><span>[Breimann23a]</span></a>.</p>
 </div>
 <div class="admonition seealso">
 <p class="admonition-title">See also</p>

docs/source/conf.py

@@ -93,7 +93,7 @@
 typehints_fully_qualified = False
 set_type_checking_flag = False
 always_document_param_types = True
-typehints_document_rtype = False
+typehints_document_rtype = False    # Check
 
 
 # Auto summary settings