From 469b56701b7fda5be950feba943a45d6cef9e21a Mon Sep 17 00:00:00 2001 From: Wenjie Du Date: Thu, 4 May 2023 12:48:09 +0800 Subject: [PATCH 1/3] fix: the footer issue on the docs home page; --- environment-dev.yml | 3 ++- setup.cfg | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/environment-dev.yml b/environment-dev.yml index 67984dd5..b5599c1a 100644 --- a/environment-dev.yml +++ b/environment-dev.yml @@ -33,7 +33,8 @@ dependencies: - conda-forge::pytest-xdist # doc - - conda-forge::sphinx + - conda-forge::sphinx ==6.2.1 + - conda-forge::docutils ==0.19 - conda-forge::sphinxcontrib-bibtex - conda-forge::furo diff --git a/setup.cfg b/setup.cfg index 7cb9eb3a..6d3cd6fd 100644 --- a/setup.cfg +++ b/setup.cfg @@ -52,7 +52,8 @@ test = # dependencies for documentation generating doc = - sphinx + sphinx==6.2.1 + docutils==0.19 sphinxcontrib-bibtex furo From 61be406a7478de917b8d3fdfea84aaeb590fcd06 Mon Sep 17 00:00:00 2001 From: Wenjie Du Date: Thu, 4 May 2023 12:50:04 +0800 Subject: [PATCH 2/3] feat: update the doc configurations; --- docs/conf.py | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index bf01b40a..5244eab3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -24,7 +24,8 @@ # -- Project information ----------------------------------------------------- project = "PyPOTS" author = "Wenjie Du" -copyright = f"{datetime.datetime.now().year}, {author}" +date_now = datetime.datetime.now() +copyright = f"{date_now.year}, {author}" # The full version, including alpha/beta/rc tags release = pypots.__version__ @@ -72,7 +73,7 @@ html_static_path = ["_static"] html_context = { - "last_updated": True, + "last_updated": f"{date_now.year}/{date_now.month}/{date_now.day}", } # https://pradyunsg.me/furo/customisation/#top-of-page-button @@ -80,3 +81,18 @@ html_theme_options = { "top_of_page_button": None, } + +html_sidebars = { + "**": [ + "sidebar/scroll-start.html", + "sidebar/brand.html", + "sidebar/search.html", + "sidebar/navigation.html", + "sidebar/scroll-end.html", + ] +} + +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "sphinx": ("https://www.sphinx-doc.org/en/master", None), +} From bacfb41c44fb3e59e7793627d914b9e34ffc984c Mon Sep 17 00:00:00 2001 From: Wenjie Du Date: Thu, 4 May 2023 12:52:03 +0800 Subject: [PATCH 3/3] docs: update the documentation; --- README.md | 5 +- docs/index.rst | 201 +++++++++++++++++++++++++++++------------- docs/pypots.utils.rst | 8 -- docs/references.rst | 5 ++ 4 files changed, 147 insertions(+), 72 deletions(-) create mode 100644 docs/references.rst diff --git a/README.md b/README.md index 1f8cbafe..415e8f5b 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ the latest release version - GPL3 license + GPL-v3 license Community @@ -102,7 +102,7 @@ PyPOTS tutorials have been released. Considering the future workload, I separate and you can find them in [BrewedPOTS](https://github.com/WenjieDu/BrewedPOTS). Take a look at it now, and brew your POTS dataset into a cup of coffee! ๐Ÿค“ -If you have further questions, please refer to PyPOTS documentation [๐Ÿ“‘https://docs.pypots.com](https://docs.pypots.com). +If you have further questions, please refer to PyPOTS documentation ๐Ÿ“‘[docs.pypots.com](https://docs.pypots.com). Besides, you can also [raise an issue](https://github.com/WenjieDu/PyPOTS/issues) or [ask in our community](#-community). We present you a usage example of imputing missing values in time series with PyPOTS below, you can click it to view. @@ -194,7 +194,6 @@ We care about the feedback from our users, so we're building PyPOTS community on If you have any suggestions or want to contribute ideas or share time-series related papers, join us and tell. PyPOTS community is open, transparent, and surely friendly. Let's work together to build and improve PyPOTS ๐Ÿ’ช! - ## โ– Contribution You're very welcome to contribute to this exciting project! diff --git a/docs/index.rst b/docs/index.rst index 91781e11..c7ad658b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,74 +1,101 @@ -.. PyPOTS documentation master file, created by - sphinx-quickstart on Wed Oct 19 17:20:43 2022. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. PyPOTS documentation master file + Created by Wenjie Du + License: GPL-v3 +Welcome to PyPOTS docs! =============================== -Welcome to PyPOTS doc! -=============================== -.. image:: https://raw.githubusercontent.com/WenjieDu/PyPOTS/main/docs/figs/PyPOTS%20logo.svg?sanitize=true - :height: 180 +.. image:: https://raw.githubusercontent.com/WenjieDu/PyPOTS/main/docs/_static/figs/PyPOTS_logo.svg?sanitize=true + :height: 168 :align: right :target: https://github.com/WenjieDu/PyPOTS :alt: PyPOTS logo .. centered:: A Python Toolbox for Data Mining on Partially-Observed Time Series -.. image:: https://img.shields.io/badge/python-v3-yellow?color=a4e2c6 +.. image:: https://img.shields.io/badge/Python-v3.7--3.10-88ada6?logo=python&logoColor=white :alt: Python version -.. 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=7fecad&label=PyPI&logo=pypi&logoColor=white - :alt: PyPI version + +.. image:: https://img.shields.io/badge/PyTorch-โค๏ธ-bbcdc5?logo=pytorch&logoColor=white + :alt: powered by Pytorch + +.. image:: https://img.shields.io/github/v/release/wenjiedu/pypots?color=e0eee8&include_prereleases&label=Release + :alt: the latest release version :target: https://pypi.org/project/pypots -.. 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 + +.. image:: https://img.shields.io/badge/License-GPL--v3-c0ebd7 + :alt: GPL-v3 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 + +.. image:: https://img.shields.io/badge/join_us-community!-7fecad + :alt: Community + :target: https://github.com/WenjieDu/PyPOTS/blob/main/README.md#-community + +.. image:: https://img.shields.io/github/sponsors/wenjiedu?label=Sponsors&color=7bcfa6&logo=githubsponsors + :alt: GitHub Sponsors + :target: https://github.com/sponsors/WenjieDu + +.. image:: https://img.shields.io/github/stars/wenjiedu/pypots?logo=Github&color=7bcfa6&label=Stars + :alt: GitHub Repo stars + :target: https://github.com/WenjieDu/PyPOTS/stargazers + +.. image:: https://img.shields.io/github/forks/wenjiedu/pypots?logo=Github&color=2edfa3&label=Forks + :alt: GitHub Repo forks + :target: https://github.com/WenjieDu/PyPOTS/forks + +.. image:: https://img.shields.io/codeclimate/maintainability-percentage/WenjieDu/PyPOTS?color=25f8cb&label=Maintainability&logo=codeclimate + :alt: Code Climate maintainability + :target: https://codeclimate.com/github/WenjieDu/PyPOTS + +.. image:: https://img.shields.io/coverallsCoverage/github/WenjieDu/PyPOTS?branch=main&logo=coveralls&color=00e09e&label=Coverage + :alt: Coveralls coverage + :target: https://coveralls.io/github/WenjieDu/PyPOTS + +.. image:: https://img.shields.io/github/actions/workflow/status/wenjiedu/pypots/testing.yml?logo=github&color=48c0a3&label=CI :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=#0aa344 - :alt: Coveralls report - :target: https://coveralls.io/github/WenjieDu/PyPOTS + +.. image:: https://img.shields.io/badge/DOI-10.5281/zenodo.6823221-21a675 + :alt: Zenodo DOI + :target: https://doi.org/10.5281/zenodo.6823221 + +.. image:: https://img.shields.io/conda/dn/conda-forge/pypots?label=Conda%20Downloads&color=057748&logo=anaconda&logoColor=white + :alt: Conda downloads + :target: https://anaconda.org/conda-forge/pypots + +.. image:: https://static.pepy.tech/personalized-badge/pypots?period=total&units=international_system&left_color=grey&right_color=teal&left_text=PyPI%20Downloads&logo=github + :alt: PyPI downloads + :target: https://pypi.org/project/pypots + .. 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 +----------------- โฆฟ `Motivation`: Due to all kinds of reasons like failure of collection sensors, communication error, and unexpected malfunction, missing values are common to see in time series from the real-world environment. This makes partially-observed time series (POTS) a pervasive problem in open-world modeling and prevents advanced data analysis. Although this problem is important, the area of data mining on POTS still lacks a dedicated toolkit. PyPOTS is created to fill in this blank. โฆฟ `Mission`: PyPOTS is born to become a handy toolbox that is going to make data mining on POTS easy rather than tedious, to help engineers and researchers focus more on the core problems in their hands rather than on how to deal with the missing parts in their data. PyPOTS will keep integrating classical and the latest state-of-the-art data mining algorithms for partially-observed multivariate time series. For sure, besides various algorithms, PyPOTS is going to have unified APIs together with detailed documentation and interactive examples across algorithms as tutorials. -.. image:: https://raw.githubusercontent.com/WenjieDu/TSDB/main/docs/figs/TSDB%20logo.svg?sanitize=true - :width: 190 +.. image:: https://raw.githubusercontent.com/WenjieDu/TSDB/main/docs/_static/figs/TSDB_logo.svg?sanitize=true + :width: 170 :alt: TSDB :align: left :target: https://github.com/WenjieDu/TSDB -To make various open-source time-series datasets readily available to our users, PyPOTS gets supported by project `TSDB (Time-Series DataBase) `_, a toolbox making loading time-series datasets super easy! +To make various open-source time-series datasets readily available to our users, PyPOTS gets supported by project `TSDB (Time-Series Data Base) `_, a toolbox making loading time-series datasets super easy! Visit `TSDB `_ right now to know more about this handy tool ๐Ÿ› ! It now supports a total of 119 open-source datasets. +The rest of this readme file is organized as follows: +`โ– Installation <#id1>`_, +`โ– Usage <#id2>`_, +`โ– Available Algorithms <#id3>`_, +`โ– Citing PyPOTS <#id13>`_, +`โ– Community <#id14>`_, +`โ– Contribution <#id15>`_. + โ– Installation -^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^ PyPOTS now is available on `Anaconda `_ โ—๏ธ Install it with ``conda install pypots``, you may need to specify the channel with option ``-c conda-forge`` @@ -81,7 +108,22 @@ or install from the source code with the latest features not officially released 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: +โ– Usage +^^^^^^^^ +.. image:: https://raw.githubusercontent.com/WenjieDu/BrewedPOTS/main/figs/BrewedPOTS_logo.jpg + :width: 160 + :alt: BrewedPOTS logo + :align: left + :target: https://github.com/WenjieDu/BrewedPOTS + +PyPOTS tutorials have been released. Considering the future workload, I separate the tutorials into a single repo, +and you can find them in `BrewedPOTS `_. +Take a look at it now, and brew your POTS dataset into a cup of coffee! ๐Ÿค“ + +If you have further questions, please refer to PyPOTS documentation ๐Ÿ“‘ `docs.pypots.com `_. +Besides, you can also `raise an issue `_ or `ask in our community <#community>`_. + +We present you a usage example of imputing missing values in time series with PyPOTS below. .. code-block:: python :linenos: @@ -109,6 +151,8 @@ Below is an example applying SAITS in PyPOTS to impute missing values in the dat โ– Available Algorithms ^^^^^^^^^^^^^^^^^^^^^^^ +PyPOTS supports imputation, classification, clustering, and forecasting tasks on multivariate time series with missing values. The currently available algorithms of four tasks are cataloged in the following table with four partitions. The paper references are all listed at the bottom of this readme file. Please refer to them if you want more details. + ============================== ================ ========================================================================= ====== ========= Task Type Algorithm Year Reference ============================== ================ ========================================================================= ====== ========= @@ -123,9 +167,14 @@ Clustering Neural Network VaDER (Variational Deep Embeddin Forecasting Probabilistic BTTF (Bayesian Temporal Tensor Factorization) 2021 :cite:`chen2021BTMF` ============================== ================ ========================================================================= ====== ========= -โ– 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. ๐Ÿค— + +โ– Citing PyPOTS +^^^^^^^^^^^^^^^^ +We are pursuing to publish a short paper introducing PyPOTS in prestigious academic venues, e.g. JMLR (track for +`Machine Learning Open Source Software `_. Before that, PyPOTS is using its DOI from Zenodo +for reference. If you use PyPOTS in your research, please cite it as below and ๐ŸŒŸstar this repository to make others +notice this work. ๐Ÿค— + .. code-block:: bibtex :linenos: @@ -142,21 +191,57 @@ or Wenjie Du. (2022). PyPOTS: A Python Toolbox for Data Mining on Partially-Observed Time Series. Zenodo. https://doi.org/10.5281/zenodo.6823221 -โ– Attention ๐Ÿ‘€ + +โ– Community +^^^^^^^^^^^^ +We care about the feedback from our users, so we're building PyPOTS community on + +- `Slack `_. General discussion, Q&A, and our development team are here; +- `LinkedIn `_. Official announcements and news are here; +- `WeChat (ๅพฎไฟกๅ…ฌไผ—ๅท) `_. We also run a group chat on WeChat, + and you can get the QR code from the official account after following it; + +If you have any suggestions or want to contribute ideas or share time-series related papers, join us and tell. +PyPOTS community is open, transparent, and surely friendly. Let's work together to build and improve PyPOTS ๐Ÿ’ช! + + +โ– Contribution ^^^^^^^^^^^^^^^ -The documentation and tutorials are under construction. And a short paper introducing PyPOTS is on the way! ๐Ÿš€ Stay tuned please! +You're very welcome to contribute to this exciting project! -โ€ผ๏ธ PyPOTS is currently under developing. If you like it and look forward to its growth, **please give PyPOTS a star and watch it to keep you posted on its progress and to let me know that its development is meaningful**. If you have any feedback, or want to contribute ideas/suggestions or share time-series related algorithms/papers, please join `our PyPOTS community `_ or create an issue. If you have any additional questions or have interests in collaboration, please take a look at `my GitHub profile `_ and feel free to contact me ๐Ÿค. +By committing your code, you'll -Thank you all for your attention! ๐Ÿ˜ƒ +1. make your well-established model out-of-the-box for PyPOTS users to run (Similar to + `Scikit-learn `_, + we set current inclusion criteria as: the paper should be published for at least 1 year, have 20+ citations, + and the usefulness to our users can be claimed); +2. be listed as one of `PyPOTS contributors `_: +3. get mentioned in our `release notes `_; +You can also contribute to PyPOTS by simply staring๐ŸŒŸ this repo to help more people notice it. +Your star is your recognition to PyPOTS, and it matters! -.. toctree:: - :maxdepth: 2 - :caption: Getting Started +The lists of PyPOTS stargazers and forkers are shown below, and we're so proud to have more and more awesome users, as well as more bright โœจstars: + +.. image:: https://reporoster.com/stars/dark/WenjieDu/PyPOTS + :alt: PyPOTS stargazers + :target: https://github.com/WenjieDu/PyPOTS/stargazers +.. image:: https://reporoster.com/forks/dark/WenjieDu/PyPOTS + :alt: PyPOTS forkers + :target: https://github.com/WenjieDu/PyPOTS/network/members - install - examples + + +โ– Attention ๐Ÿ‘€ +^^^^^^^^^^^^^^^ +PyPOTS is currently under developing. If you like it and look forward to its growth, **please give PyPOTS a star +and watch it to keep you posted on its progress and to let me know that its development is meaningful**. +If you have any additional questions or have interests in collaboration, please take a look at +`my GitHub profile `_ and feel free to contact me ๐Ÿค. + +Thank you all for your attention! ๐Ÿ˜ƒ + +----------------- .. toctree:: :maxdepth: 2 @@ -170,10 +255,4 @@ Thank you all for your attention! ๐Ÿ˜ƒ :hidden: :caption: Additional Information - faq - about_us - - -References -"""""""""" -.. bibliography:: \ No newline at end of file + references diff --git a/docs/pypots.utils.rst b/docs/pypots.utils.rst index 33ab1664..2331064f 100644 --- a/docs/pypots.utils.rst +++ b/docs/pypots.utils.rst @@ -1,14 +1,6 @@ pypots.utils package ==================== -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - pypots.utils.commands - Submodules ---------- diff --git a/docs/references.rst b/docs/references.rst new file mode 100644 index 00000000..f5072e18 --- /dev/null +++ b/docs/references.rst @@ -0,0 +1,5 @@ +References +========== + +.. bibliography:: + :style: unsrt