MNT refactor the project structure (#27)

* MNT refactor the project structure

Author: MatthewSZhang

doc/index.rst

@@ -9,33 +9,41 @@
 
 .. include:: ../README.rst
 
-.. currentmodule:: fastcan
 
 
 API Reference
 -------------
-.. autosummary::
-   :toctree: generated/
-
-   FastCan
-   refine
-   minibatch
-   ssc
-   ols
-   make_poly_ids
-   make_poly_features
-   make_time_shift_features
-   make_time_shift_ids
-   make_narx
-   print_narx
-   Narx
+.. automodule:: fastcan
+
+   .. rubric:: Classes
+
+   .. autosummary::
+      :toctree: generated/
+
+         FastCan
+   
+   .. rubric:: Functions
+
+   .. autosummary::
+      :toctree: generated/
+
+         refine
+         minibatch
+   
+   .. rubric:: Submodules
+
+   .. autosummary::
+      :toctree: generated/
+
+         narx
+         utils
 
 Useful Links
 ------------
 .. toctree::
    :maxdepth: 2
 
-   User Guild <user_guide>
+   User Guide <user_guide>
    Examples <auto_examples/index>
 
 API Compatibility

doc/templates/autosummary/module.rst

@@ -0,0 +1,28 @@
+{{ objname | escape | underline(line="=") }}
+
+.. automodule:: {{ fullname }}
+
+    {% block classes %}
+    {% if classes %}
+    .. rubric:: {{ _('Classes') }}
+
+    .. autosummary::
+        :toctree:
+    {% for item in classes %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+
+    {% block functions %}
+    {% if functions %}
+    .. rubric:: {{ _('Functions') }}
+
+    .. autosummary::
+        :toctree:
+    {% for item in functions %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}

examples/plot_affinity.py

@@ -23,7 +23,8 @@
 from sklearn.datasets import load_diabetes
 from sklearn.linear_model import OrthogonalMatchingPursuit
 
-from fastcan import FastCan, ols
+from fastcan import FastCan
+from fastcan.utils import ols
 
 X, y = load_diabetes(return_X_y=True)
 

examples/plot_speed.py

@@ -39,7 +39,7 @@
 # canonical correlation coefficients may be more than one, the feature ranking
 # criterion used here is the sum squared of all canonical correlation coefficients.
 
-from fastcan import ssc
+from fastcan.utils import ssc
 
 
 def baseline(X, y, t):

fastcan/__init__.py

@@ -1,32 +1,17 @@
 """
-The :mod:`fastcan` module implements algorithms, including
+The implementation of fast canonical correlation analysis based feature selection
+algorithm.
 """
 
+from . import narx, utils
 from ._fastcan import FastCan
 from ._minibatch import minibatch
-from ._narx import (
-    Narx,
-    make_narx,
-    make_poly_features,
-    make_poly_ids,
-    make_time_shift_features,
-    make_time_shift_ids,
-    print_narx,
-)
 from ._refine import refine
-from ._utils import ols, ssc
 
 __all__ = [
     "FastCan",
-    "ssc",
-    "ols",
     "refine",
     "minibatch",
-    "make_narx",
-    "print_narx",
-    "Narx",
-    "make_poly_features",
-    "make_poly_ids",
-    "make_time_shift_features",
-    "make_time_shift_ids",
+    "narx",
+    "utils",
 ]

fastcan/_minibatch.py

@@ -1,5 +1,5 @@
 """
-Feature selection with mini-batch
+Feature selection with mini-batch.
 """
 
 from copy import deepcopy
@@ -29,7 +29,7 @@
     prefer_skip_nested_validation=False,
 )
 def minibatch(X, y, n_features_to_select=1, batch_size=1, verbose=1):
-    """FastCan selection with mini batches.
+    """Feature selection using :class:`fastcan.FastCan` with mini batches.
 
     It is suitable for selecting a very large number of features
     even larger than the number of samples.

fastcan/_refine.py

@@ -31,7 +31,7 @@
     prefer_skip_nested_validation=True,
 )
 def refine(selector, drop=1, max_iter=None, verbose=1):
-    """Two-Stage Refining.
+    """Two-stage refining for the results of :class:`fastcan.FastCan`.
 
     In the refining process, the selected features will be dropped, and
     the vacancy positions will be refilled from the candidate features.

fastcan/_narx.py renamed to fastcan/narx.py

@@ -1,5 +1,6 @@
 """
-This file contains Narx model class.
+The module related to nonlinear autoregressive exogenous (NARX) model for system
+identification.
 """
 
 import math
@@ -47,7 +48,7 @@ def make_time_shift_features(X, ids):
 
     Examples
     --------
-    >>> from fastcan import make_time_shift_features
+    >>> from fastcan.narx import make_time_shift_features
     >>> X = [[1, 2], [3, 4], [5, 6], [7, 8]]
     >>> ids = [[0, 0], [0, 1], [1, 1]]
     >>> make_time_shift_features(X, ids)
@@ -108,7 +109,7 @@ def make_time_shift_ids(
 
     Examples
     --------
-    >>> from fastcan import make_time_shift_ids
+    >>> from fastcan.narx import make_time_shift_ids
     >>> make_time_shift_ids(2, max_delay=3, include_zero_delay=[True, False])
     array([[0, 0],
            [0, 1],
@@ -172,7 +173,7 @@ def make_poly_features(X, ids):
 
     Examples
     --------
-    >>> from fastcan import make_poly_features
+    >>> from fastcan.narx import make_poly_features
     >>> X = [[1, 2], [3, 4], [5, 6], [7, 8]]
     >>> ids = [[0, 0], [0, 1], [1, 1], [0, 2]]
     >>> make_poly_features(X, ids)
@@ -233,7 +234,7 @@ def make_poly_ids(
 
     Examples
     --------
-    >>> from fastcan import make_poly_ids
+    >>> from fastcan.narx import make_poly_ids
     >>> make_poly_ids(2, degree=3)
     array([[0, 0, 1],
            [0, 0, 2],
@@ -274,7 +275,7 @@ def _mask_missing_value(*arr):
 
 
 class Narx(RegressorMixin, BaseEstimator):
-    """Nonlinear Autoregressive eXogenous model.
+    """The Nonlinear Autoregressive eXogenous (NARX) model class.
     For example, a (polynomial) Narx model is like
     y(t) = y(t-1)*u(t-1) + u(t-1)^2 + u(t-2) + 1.5
     where y(t) is the system output at time t,
@@ -332,7 +333,7 @@ class Narx(RegressorMixin, BaseEstimator):
     Examples
     --------
     >>> import numpy as np
-    >>> from fastcan import Narx, print_narx
+    >>> from fastcan.narx import Narx, print_narx
     >>> rng = np.random.default_rng(12345)
     >>> n_samples = 1000
     >>> max_delay = 3
@@ -675,7 +676,7 @@ def print_narx(
     Examples
     --------
     >>> from sklearn.datasets import load_diabetes
-    >>> from fastcan import print_narx, Narx
+    >>> from fastcan.narx import print_narx, Narx
     >>> X, y = load_diabetes(return_X_y=True)
     >>> print_narx(Narx().fit(X, y), term_space=10, coef_space=5, float_precision=0)
     |   Term   |Coef |
@@ -816,7 +817,7 @@ def make_narx(
     --------
     >>> import numpy as np
     >>> from sklearn.metrics import mean_squared_error
-    >>> from fastcan import make_narx, print_narx
+    >>> from fastcan.narx import make_narx, print_narx
     >>> rng = np.random.default_rng(12345)
     >>> n_samples = 1000
     >>> max_delay = 3

fastcan/_utils.py renamed to fastcan/utils.py

@@ -1,4 +1,4 @@
-"""Sum squared of correlation."""
+"""Utils functions."""
 
 from numbers import Integral
 
@@ -33,7 +33,7 @@ def ssc(X, y):
 
     Examples
     --------
-    >>> from fastcan import ssc
+    >>> from fastcan.utils import ssc
     >>> X = [[1], [-1], [0]]
     >>> y = [[0], [1], [-1]]
     >>> ssc(X, y)
@@ -58,7 +58,7 @@ def ssc(X, y):
     prefer_skip_nested_validation=True,
 )
 def ols(X, y, t=1):
-    """Orthogonal least-squares
+    """Orthogonal least-squares.
 
     Parameters
     ----------
@@ -83,7 +83,7 @@ def ols(X, y, t=1):
 
     Examples
     --------
-    >>> from fastcan import ols
+    >>> from fastcan.utils import ols
     >>> X = [[1, 0, 0], [0, 1, 0], [0, 0, 1], [0, 0, 0]]
     >>> y = [1, 0, 1, 0]
     >>> indices, scores = ols(X, y, 2)