Merge dev into main to update the documentation and add doc-gener…

…ating shell scripts (#40) * doc: update the documentation; * doc: update the documentation;
WenjieDu · Apr 4, 2023 · 3ac3185 · 3ac3185
1 parent f64dda9
commit 3ac3185
Show file tree

Hide file tree

Showing 5 changed files with 87 additions and 24 deletions.
diff --git a/README.md b/README.md
@@ -21,7 +21,9 @@
         <img src='https://img.shields.io/badge/License-GPL--v3-00e09e'>
     </a>
     <!-- Repo size -->
-    <img src="https://img.shields.io/github/repo-size/WenjieDu/PyPOTS?color=48c0a3">
+    <a alt='Repo size' href='https://github.com/WenjieDu/PyPOTS'>
+        <img src="https://img.shields.io/github/repo-size/WenjieDu/PyPOTS?color=48c0a3">
+    </a>
     <!-- Code of Conduct -->
     <a alt='CODE_OF_CONDUCT' href='https://github.com/WenjieDu/PyPOTS/blob/main/CODE_OF_CONDUCT.md'> 
         <img src='https://img.shields.io/badge/Contributor%20Covenant-v2.1-21a675.svg'>
@@ -110,6 +112,7 @@ mae = cal_mae(imputation, X_intact, indicating_mask)  # calculate mean absolute
 | Forecasting                   | Probabilistic  | BTTF (Bayesian Temporal Tensor Factorization)                            | 2021 | [^8]      |
 
 ## ❖ Reference
+## ❖ Cite PyPOTS
 If you find PyPOTS is helpful to your research, please cite it as below and ⭐️star this repository to make others notice this work. 🤗
 
 ```bibtex

diff --git a/docs/gene_html_and_review.sh b/docs/gene_html_and_review.sh
@@ -0,0 +1,7 @@
+# Created by Wenjie Du <wenjay.du@gmail.com>
+# License: GPL-v3
+
+# This shell script is created to help generate PyPOTS html documentation for review before publishing.
+
+make html && \
+  python -m http.server 8099 -d _build/html
diff --git a/docs/gene_new_doc.sh b/docs/gene_new_doc.sh
@@ -0,0 +1,22 @@
+# Created by Wenjie Du <wenjay.du@gmail.com>
+# License: GPL-v3
+
+# This shell script is created to help generate PyPOTS documentation.
+
+git clone https://github.com/WenjieDu/PyPOTS pypots_latest && rm -rf pypots_latest/pypots/tests
+
+# Generate the docs according to the latest code on branch main
+SPHINX_APIDOC_OPTIONS=members,undoc-members,show-inheritance sphinx-apidoc pypots_latest -o pypots_latest/rst
+
+# Only save the files we need.
+cp pypots_latest/rst/pypots.classification.rst \
+  pypots_latest/rst/pypots.clustering.rst \
+  pypots_latest/rst/pypots.data.rst \
+  pypots_latest/rst/pypots.forecasting.rst \
+  pypots_latest/rst/pypots.imputation.rst \
+  pypots_latest/rst/pypots.rst \
+  pypots_latest/rst/pypots.utils.rst \
+    .
+
+# Delete the useless files.
+rm -rf pypots_latest
diff --git a/docs/index.rst b/docs/index.rst
@@ -14,34 +14,40 @@ Welcome to PyPOTS doc!
 
 .. centered:: A Python Toolbox for Data Mining on Partially-Observed Time Series
 
-.. image:: https://img.shields.io/badge/python-v3-yellowgreen
+.. image:: https://img.shields.io/badge/python-v3-yellow?color=a4e2c6
    :alt: Python version
-.. image:: https://img.shields.io/static/v1?label=%E2%9D%A4%EF%B8%8F&message=PyTorch&color=DC583A
+.. image:: https://img.shields.io/static/v1?label=PyTorch&message=%E2%9D%A4%EF%B8%8F&color=7bcfa6&logo=pytorch
    :alt: PyTorch as backend
-.. image:: https://img.shields.io/pypi/v/pypots?color=green&label=PyPI
+.. image:: https://img.shields.io/pypi/v/pypots?color=7fecad&label=PyPI&logo=pypi&logoColor=white
    :alt: PyPI version
    :target: https://pypi.org/project/pypots
-.. image:: https://img.shields.io/badge/License-GPL--v3-green?color=79C641
+.. image:: https://img.shields.io/conda/pn/conda-forge/pypots?color=3de1ad&label=Conda&logo=anaconda
+   :alt: on Anaconda
+   :target: https://anaconda.org/conda-forge/pypots
+.. image:: https://img.shields.io/badge/License-GPL--v3-00e09e
    :alt: License
    :target: https://github.com/WenjieDu/PyPOTS/blob/main/LICENSE
+.. image:: https://img.shields.io/github/repo-size/WenjieDu/PyPOTS?color=48c0a3
+   :alt: Repo size
+   :target: https://github.com/WenjieDu/PyPOTS
+.. image:: https://img.shields.io/badge/Contributor%20Covenant-v2.1-21a675.svg
+   :alt: Code of Conduct
+   :target: https://github.com/WenjieDu/PyPOTS/blob/main/CODE_OF_CONDUCT.md
+.. image:: https://img.shields.io/badge/Slack-PyPOTS-grey?logo=slack&color=549688
+   :alt: Slack workspace
+   :target: https://join.slack.com/t/pypots-dev/shared_invite/zt-1gq6ufwsi-p0OZdW~e9UW_IA4_f1OfxA
+.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.6823221.svg
+   :alt: Zenodo DOI
+   :target: https://doi.org/10.5281/zenodo.6823221
+.. image:: https://static.pepy.tech/personalized-badge/pypots?period=total&units=international_system&left_color=grey&right_color=navy&left_text=Downloads
+   :alt: PyPI download number
+   :target: https://pepy.tech/project/pypots
 .. image:: https://github.com/WenjieDu/PyPOTS/actions/workflows/testing.yml/badge.svg
    :alt: GitHub Testing
    :target: https://github.com/WenjieDu/PyPOTS/actions/workflows/testing.yml
-.. image:: https://img.shields.io/coverallsCoverage/github/WenjieDu/PyPOTS?branch=main&logo=coveralls&labelColor=3F5767
+.. image:: https://img.shields.io/coverallsCoverage/github/WenjieDu/PyPOTS?branch=main&logo=coveralls&labelColor=#0aa344
    :alt: Coveralls report
    :target: https://coveralls.io/github/WenjieDu/PyPOTS
-.. image:: https://static.pepy.tech/personalized-badge/pypots?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Downloads
-   :alt: PyPI download number
-   :target: https://pepy.tech/project/pypots
-.. image:: https://zenodo.org/badge/475477908.svg
-   :alt: Zenodo DOI
-   :target: https://zenodo.org/badge/latestdoi/475477908
-.. image:: https://img.shields.io/badge/Contributor%20Covenant-v2.1-4baaaa.svg
-   :alt: Code of Conduct
-   :target: https://github.com/WenjieDu/PyPOTS/blob/main/CODE_OF_CONDUCT.md
-.. image:: https://img.shields.io/badge/Slack-PyPOTS-grey?logo=slack&labelColor=4A154B&color=62BCE5
-   :alt: Slack workspace
-   :target: https://join.slack.com/t/pypots-dev/shared_invite/zt-1gq6ufwsi-p0OZdW~e9UW_IA4_f1OfxA
 .. image:: https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FPyPOTS%2FPyPOTS&count_bg=%23009A0A&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=Visits&edge_flat=false
    :alt: Visiting number
 
@@ -63,10 +69,18 @@ Visit `TSDB <https://github.com/WenjieDu/TSDB>`_ right now to know more about th
 
 ❖ Installation
 ^^^^^^^^^^^^^^^^
+PyPOTS now is available on `Anaconda <https://anaconda.org/conda-forge/pypots>`_ ❗️
+
+Install it with ``conda install pypots``, you may need to specify the channel with option ``-c conda-forge``
+
 Install the latest release from PyPI:
 
    pip install pypots
 
+or install from the source code with the latest features not officially released in a version:
+
+   pip install https://github.com/WenjieDu/PyPOTS/archive/main.zip
+
 Below is an example applying SAITS in PyPOTS to impute missing values in the dataset PhysioNet2012:
 
 .. code-block:: python
@@ -86,10 +100,11 @@ Below is an example applying SAITS in PyPOTS to impute missing values in the dat
    X = X.reshape(num_samples, 48, -1)
    X_intact, X, missing_mask, indicating_mask = mcar(X, 0.1) # hold out 10% observed values as ground truth
    X = masked_fill(X, 1 - missing_mask, np.nan)
+   dataset = {"X": X}
    # Model training. This is PyPOTS showtime. 💪
    saits = SAITS(n_steps=48, n_features=37, n_layers=2, d_model=256, d_inner=128, n_head=4, d_k=64, d_v=64, dropout=0.1, epochs=10)
-   saits.fit(X)  # train the model. Here I use the whole dataset as the training set, because ground truth is not visible to the model.
-   imputation = saits.impute(X)  # impute the originally-missing values and artificially-missing values
+   saits.fit(dataset)  # train the model. Here I use the whole dataset as the training set, because ground truth is not visible to the model.
+   imputation = saits.impute(dataset)  # impute the originally-missing values and artificially-missing values
    mae = cal_mae(imputation, X_intact, indicating_mask)  # calculate mean absolute error on the ground truth (artificially-missing values)
 
 ❖ Available Algorithms
@@ -108,8 +123,8 @@ Clustering                     Neural Network   VaDER (Variational Deep Embeddin
 Forecasting                    Probabilistic    BTTF (Bayesian Temporal Tensor Factorization)                              2021   :cite:`chen2021BTMF`
 ============================== ================ =========================================================================  ====== =========
 
-❖ Citing PyPOTS
-^^^^^^^^^^^^^^^^
+❖ Cite PyPOTS
+^^^^^^^^^^^^^^
 If you find PyPOTS is helpful to your research, please cite it as below and ⭐️star this repository to make others notice this work. 🤗
 
 .. code-block:: bibtex
@@ -120,12 +135,12 @@ If you find PyPOTS is helpful to your research, please cite it as below and ⭐
    title = {{PyPOTS: A Python Toolbox for Data Mining on Partially-Observed Time Series}},
    howpublished = {\url{https://github.com/wenjiedu/pypots}},
    year = {2022},
-   doi = {10.5281/zenodo.6823222},
+   doi = {10.5281/zenodo.6823221},
    }
 
 or
 
-   Wenjie Du. (2022). PyPOTS: A Python Toolbox for Data Mining on Partially-Observed Time Series. Zenodo. https://doi.org/10.5281/zenodo.6823222
+   Wenjie Du. (2022). PyPOTS: A Python Toolbox for Data Mining on Partially-Observed Time Series. Zenodo. https://doi.org/10.5281/zenodo.6823221
 
 ❖ Attention 👀
 ^^^^^^^^^^^^^^^

diff --git a/docs/pypots.utils.rst b/docs/pypots.utils.rst
@@ -4,6 +4,22 @@ pypots.utils package
 Submodules
 ----------
 
+pypots.utils.files module
+-------------------------
+
+.. automodule:: pypots.utils.files
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pypots.utils.logging module
+---------------------------
+
+.. automodule:: pypots.utils.logging
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 pypots.utils.metrics module
 ---------------------------