DOC add speed example

Author: MatthewSZhang

.gitignore

@@ -28,4 +28,6 @@ wheels/
 
 # Used by sphinx
 doc/_build/
-doc/generated/
+doc/generated/
+doc/auto_examples/
+doc/sg_execution_times.rst

.readthedocs.yml

@@ -11,4 +11,4 @@ python:
   install:
     - method: pip
       path: .
-      extra_requirements: [doc]
+      extra_requirements: [docs]

README.rst

@@ -1,5 +1,5 @@
-FastCan: A Fast Canonical-Correlation-Based Feature Selection Method
-====================================================================
+FastCan: A Fast Canonical-Correlation-Based Feature Selection Algorithm
+=======================================================================
 |conda| |Codecov| |CI| |Doc| |PythonVersion| |PyPi| |Black| |ruff| |pixi|
 
 .. |conda| image:: https://img.shields.io/conda/vn/conda-forge/fastcan.svg
@@ -29,6 +29,16 @@ FastCan: A Fast Canonical-Correlation-Based Feature Selection Method
 .. |pixi| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json&style=flat-square
    :target: https://pixi.sh
 
+FastCan is a feature selection method, which has following advantages:
+
+#. Extremely **fast**. See :ref:`sphx_glr_auto_examples_plot_speed.py`.
+
+#. Support unsupervised feature selection.
+
+#. Support multioutput feature selection.
+
+#. Skip redundant features.
+
 
 Installation
 ------------
@@ -41,25 +51,22 @@ Or via conda-forge:
 
 * Run ``conda install -c conda-forge fastcan``
 
-Examples
---------
+Getting Started
+---------------
 >>> from fastcan import FastCan
->>> X = [[ 0.87, -1.34,  0.31 ],
-...     [-2.79, -0.02, -0.85 ],
-...     [-1.34, -0.48, -2.55 ],
-...     [ 1.92,  1.48,  0.65 ]]
->>> y = [0, 1, 0, 1]
->>> selector = FastCan(n_features_to_select=2, verbose=0).fit(X, y)
->>> selector.get_support()
-array([ True,  True, False])
+>>> X = [[1, 0], [0, 1]]
+>>> y = [1, 0]
+>>> FastCan(verbose=0).fit(X, y).get_support()
+array([ True, False])
 
+Check :ref:`User Guild <user_guide>` and :ref:`Examples <examples>` for more information.
 
 Citation
 --------
 
 FastCan is a Python implementation of the following papers.
 
-If you use the `h-correlation` algorithm in your work please cite the following reference:
+If you use the `h-correlation` method in your work please cite the following reference:
 
 .. code:: bibtex
 
@@ -76,7 +83,7 @@ If you use the `h-correlation` algorithm in your work please cite the following
       keywords = {Feature selection, Orthogonal least squares, Canonical correlation analysis, Linear discriminant analysis, Multi-label, Multivariate time series, Feature interaction},
       }
 
-If you use the `eta-cosine` algorithm in your work please cite the following reference:
+If you use the `eta-cosine` method in your work please cite the following reference:
 
 .. code:: bibtex
 

doc/conf.py

@@ -40,6 +40,8 @@
     "sphinx.ext.napoleon",
     # Link to other project's documentation (see mapping below)
     "sphinx.ext.intersphinx",
+    "sphinx_gallery.gen_gallery",
+    "sphinx_design",
 ]
 
 # List of patterns, relative to source directory, that match files and
@@ -67,14 +69,7 @@
     "sklearn": ("https://scikit-learn.org/stable", None),
 }
 
-# add substitutions that should be available in every file
-rst_prolog = """
-.. |numpy_dtype| replace:: numpy data type
-.. _numpy_dtype: https://numpy.org/doc/stable/user/basics.types.html
-
-.. |sklearn_cython_dtype| replace:: sklearn cython data type
-.. _sklearn_cython_dtype: https://github.com/scikit-learn/scikit-learn/blob/main/sklearn/utils/_typedefs.pxd
-
-.. |sphinx_link| replace:: rst Markup Spec
-.. _sphinx_link: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
-"""
+sphinx_gallery_conf = {
+    "examples_dirs": ["../examples"],
+    "gallery_dirs": ["auto_examples"],
+}

doc/index.rst

@@ -13,14 +13,21 @@
 
 
 FastCan Class
-~~~~~~~~~~~~~
+-------------
 .. autosummary::
    :toctree: generated/
 
    FastCan
 
+Useful Links
+------------
+.. toctree::
 
-...................
+   User Guild <user_guide>
+   Examples <auto_examples/index>
+
+API Compatibility
+-----------------
 
 The API of this package is align with scikit-learn.
 

doc/intuitive.rst

@@ -0,0 +1,16 @@
+.. currentmodule:: fastcan
+
+.. _intuitive:
+
+=======================
+Intuitively explanation
+=======================
+
+Let's intuitively understand the two methods, h-correlation and eta-cosine, in :class:`FastCan`.
+
+The computational speed comparison between h-correlation method and eta-cosine method.
+
+.. figure:: ./auto_examples/images/sphx_glr_plot_speed_001.png
+  :target: ./auto_examples/plot_speed.html
+  :align: center
+  :scale: 70%

doc/multioutput.rst

@@ -0,0 +1,9 @@
+.. currentmodule:: fastcan
+
+.. _multioutput:
+
+==============================
+Multioutput feature selection
+==============================
+
+We can use :class:`FastCan` for multioutput feature selection.

doc/redundancy.rst

@@ -0,0 +1,9 @@
+.. currentmodule:: fastcan
+
+.. _redundancy:
+
+==================
+Feature redundancy
+==================
+
+:class:`FastCan` can effectively skip the redundant features.

doc/unsupervised.rst

@@ -0,0 +1,9 @@
+.. currentmodule:: fastcan
+
+.. _unsupervised:
+
+==============================
+Unsupervised feature selection
+==============================
+
+We can use :class:`FastCan` to do unsupervised feature selection.

doc/user_guide.rst

@@ -0,0 +1,13 @@
+.. _user_guide:
+
+==========
+User Guide
+==========
+
+.. toctree::
+   :numbered:
+
+   intuitive.rst
+   unsupervised.rst
+   multioutput.rst
+   redundancy.rst