From 1ab18d085fb97feaaf8d49ac767e3b6efec01d16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Franz=20Kir=C3=A1ly?= Date: Wed, 13 Sep 2023 00:10:31 +0200 Subject: [PATCH 1/2] [DOC] rework of `sphinx` docs - part 4 (#93) Fixing link and structure issues. --- docs/source/changelog.rst | 52 ++++++++++++++++++- docs/source/conf.py | 4 -- docs/source/get_started.rst | 2 +- docs/source/installation.rst | 4 +- .../related_software.rst | 0 .../{user_documentation => }/tutorials.rst | 0 docs/source/user_documentation/changelog.rst | 51 ------------------ .../{user_documentation => }/user_guide.rst | 0 docs/source/users.rst | 41 +++++---------- 9 files changed, 66 insertions(+), 88 deletions(-) rename docs/source/{user_documentation => }/related_software.rst (100%) rename docs/source/{user_documentation => }/tutorials.rst (100%) delete mode 100644 docs/source/user_documentation/changelog.rst rename docs/source/{user_documentation => }/user_guide.rst (100%) diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index f6cf854a3..5bf93418b 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -1,3 +1,51 @@ -.. _top_level_changelog: +========= +Changelog +========= -.. include:: user_documentation/changelog.rst +All notable changes to this project beggining with version 0.1.0 will be +documented in this file. The format is based on +`Keep a Changelog `_ and we adhere +to `Semantic Versioning `_. The source +code for all `releases `_ +is available on GitHub. + +You can also subscribe to ``skpro``'s +`PyPi release `_. + +For planned changes and upcoming releases, see our :ref:`roadmap`. + +[2.0.0] - 2023-09-1X +==================== + +Re-release of ``skpro``, newly rearchitected using ``skbase``. + +Highlights +---------- + +Enhancements +------------ + +Fixes +----- + +Documentation +------------- + +Maintenance +----------- + +Contributors +------------ +:user:`Alex-JG3`, +:user:`fkiraly`, +:user:`frthjf` + +[1.0.1] - 2019-02-18 +==================== + +First stable release of ``skpro``, last release before hiatus. + +[1.0.0b] - 2017-12-08 +===================== + +First public release (beta) of ``skpro``. diff --git a/docs/source/conf.py b/docs/source/conf.py index 76042e2c8..a8fab2b4f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -164,10 +164,6 @@ def find_source(): version_match = "v" + release html_theme_options = { - "logo": { - "text": "skpro", - "alt_text": "skpro", - }, "icon_links": [ { "name": "GitHub", diff --git a/docs/source/get_started.rst b/docs/source/get_started.rst index 2ed70d138..a887a3efe 100644 --- a/docs/source/get_started.rst +++ b/docs/source/get_started.rst @@ -17,6 +17,6 @@ Installation * operating systems Mac OS X, Unix-like OS, Windows 8.1 and higher * installation via ``PyPi`` or ``conda`` -Please see the :ref:`installation ` guide for step-by-step instructions on the package installation. +Please see the :ref:`installation ` guide for step-by-step instructions on the package installation. .. _scikit-learn: https://scikit-learn.org/stable/index.html diff --git a/docs/source/installation.rst b/docs/source/installation.rst index c5b785ad6..4902b415e 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -33,13 +33,13 @@ code snippets below. .. code-block:: bash - pip install scikit-base + pip install skpro .. tab-item:: PyPi (all dependencies) .. code-block:: bash - pip install scikit-base[all_extras] + pip install skpro[all_extras] .. tab-item:: Conda diff --git a/docs/source/user_documentation/related_software.rst b/docs/source/related_software.rst similarity index 100% rename from docs/source/user_documentation/related_software.rst rename to docs/source/related_software.rst diff --git a/docs/source/user_documentation/tutorials.rst b/docs/source/tutorials.rst similarity index 100% rename from docs/source/user_documentation/tutorials.rst rename to docs/source/tutorials.rst diff --git a/docs/source/user_documentation/changelog.rst b/docs/source/user_documentation/changelog.rst deleted file mode 100644 index 5bf93418b..000000000 --- a/docs/source/user_documentation/changelog.rst +++ /dev/null @@ -1,51 +0,0 @@ -========= -Changelog -========= - -All notable changes to this project beggining with version 0.1.0 will be -documented in this file. The format is based on -`Keep a Changelog `_ and we adhere -to `Semantic Versioning `_. The source -code for all `releases `_ -is available on GitHub. - -You can also subscribe to ``skpro``'s -`PyPi release `_. - -For planned changes and upcoming releases, see our :ref:`roadmap`. - -[2.0.0] - 2023-09-1X -==================== - -Re-release of ``skpro``, newly rearchitected using ``skbase``. - -Highlights ----------- - -Enhancements ------------- - -Fixes ------ - -Documentation -------------- - -Maintenance ------------ - -Contributors ------------- -:user:`Alex-JG3`, -:user:`fkiraly`, -:user:`frthjf` - -[1.0.1] - 2019-02-18 -==================== - -First stable release of ``skpro``, last release before hiatus. - -[1.0.0b] - 2017-12-08 -===================== - -First public release (beta) of ``skpro``. diff --git a/docs/source/user_documentation/user_guide.rst b/docs/source/user_guide.rst similarity index 100% rename from docs/source/user_documentation/user_guide.rst rename to docs/source/user_guide.rst diff --git a/docs/source/users.rst b/docs/source/users.rst index d0989b24c..8ce06235d 100644 --- a/docs/source/users.rst +++ b/docs/source/users.rst @@ -8,12 +8,11 @@ Documentation :maxdepth: 1 :hidden: - user_documentation/installation - user_documentation/tutorials - user_documentation/user_guide - user_documentation/glossary - user_documentation/changelog - user_documentation/related_software + installation + tutorials + user_guide + changelog + related_software .. grid:: 1 2 2 2 @@ -22,11 +21,11 @@ Documentation .. grid-item-card:: Installation :text-align: center - Install ``skbase``. + Install ``skpro``. +++ - .. button-ref:: user_documentation/installation + .. button-ref:: installation :color: primary :click-parent: :expand: @@ -40,7 +39,7 @@ Documentation +++ - .. button-ref:: user_documentation/tutorials + .. button-ref:: tutorials :color: primary :click-parent: :expand: @@ -50,31 +49,17 @@ Documentation .. grid-item-card:: User Guide :text-align: center - Learn about using ``skbase``. + Learn about using ``skpro``. +++ - .. button-ref:: user_documentation/user_guide + .. button-ref:: user_guide :color: primary :click-parent: :expand: User Guide - .. grid-item-card:: Glossary - :text-align: center - - Understand common terminology. - - +++ - - .. button-ref:: user_documentation/glossary - :color: primary - :click-parent: - :expand: - - Glossary - .. grid-item-card:: Changelog :text-align: center @@ -82,7 +67,7 @@ Documentation +++ - .. button-ref:: user_documentation/changelog + .. button-ref:: changelog :color: primary :click-parent: :expand: @@ -92,11 +77,11 @@ Documentation .. grid-item-card:: Related Software :text-align: center - Explore software related to ``skbase``. + Explore software related to ``skpro``. +++ - .. button-ref:: user_documentation/related_software + .. button-ref:: related_software :color: primary :click-parent: :expand: From da21f8d45c097862c5e81b556250d253ce123cd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Franz=20Kir=C3=A1ly?= Date: Wed, 13 Sep 2023 09:36:03 +0200 Subject: [PATCH 2/2] [DOC] updating the README for the 2.0 release (#79) This PR updates the README for the 2.0 release: * 2.0 code snippets * updated community and contribution links * updated documentation references --- README.md | 181 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 159 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index e78bcbef5..0e3b7c898 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,175 @@ -**CAUTION: the skpro package is currently undergoing major rearchitecting and should not be used in deployment.** + + +**NOTE: for historical reasons, version numbers of maturing versions start at 2.0.0.** If you find this package interesting and would like to contribute, kindly contact the `sktime` developers in the [skpro & probabilistic forecasting workstream on discord](https://discord.com/channels/1075852648688930887/1106258090568986644). -![skpro](/docs/_static/logo/skpro-banner.png) +`skpro` is a library for supervised probabilistic prediction in python. +It provides `scikit-learn`-like, `scikit-base` compatible interfaces to: + +* tabular **supervised regressors with probabilistic prediction modes** - interval, quantile and distribution predictions +* **performance metrics to evaluate probabilistic predictions**, e.g., pinball loss, empirical coverage, CRPS +* **reductions** to turn non-probabilistic, `scikit-learn` regressors into probabilistic `skpro` regressors, such as bootstrap or conformal +* tools for building **pipelines and composite machine learning models**, including tuning via probabilistic performance metrics +* symbolic and lazy **probability distributions** with a value domain of `pandas.DataFrame`-s and a `pandas`-like interface + + +| Overview | | +|---|---| +| **Open Source** | [![BSD 3-clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/sktime/sktime/blob/main/LICENSE) | +| **Community** | [![!discord](https://img.shields.io/static/v1?logo=discord&label=discord&message=chat&color=lightgreen)](https://discord.com/invite/54ACzaFsn7) [![!slack](https://img.shields.io/static/v1?logo=linkedin&label=LinkedIn&message=news&color=lightblue)](https://www.linkedin.com/company/scikit-time/) [![!youtube](https://img.shields.io/static/v1?logo=youtube&label=YouTube&message=tutorials&color=red)](https://www.youtube.com/playlist?list=PLKs3UgGjlWHqNzu0LEOeLKvnjvvest2d0) | +| **CI/CD** | [![github-actions](https://img.shields.io/github/actions/workflow/status/sktime/sktime/wheels.yml?logo=github)](https://github.com/sktime/skpro/actions/workflows/wheels.yml) [![!codecov](https://img.shields.io/codecov/c/github/sktime/skpro?label=codecov&logo=codecov)](https://codecov.io/gh/sktime/skpro) [![readthedocs](https://img.shields.io/readthedocs/skpro?logo=readthedocs)](https://skpro.readthedocs.io/en/latest/) [![platform](https://img.shields.io/conda/pn/conda-forge/skpro)](https://github.com/sktime/skpro) | +| **Code** | [![!pypi](https://img.shields.io/pypi/v/skpro?color=orange)](https://pypi.org/project/skpro/) [![!conda](https://img.shields.io/conda/vn/conda-forge/skpro)](https://anaconda.org/conda-forge/skpro) [![!python-versions](https://img.shields.io/pypi/pyversions/skpro)](https://www.python.org/) [![!black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/sktime/skpro/main?filepath=examples) | + + +## :books: Documentation + +| Documentation | | +| -------------------------- | -------------------------------------------------------------- | +| :star: **[Tutorials]** | New to skpro? Here's everything you need to know! | +| :clipboard: **[Binder Notebooks]** | Example notebooks to play with in your browser. | +| :woman_technologist: **[User Guides]** | How to use skpro and its features. | +| :scissors: **[Extension Templates]** | How to build your own estimator using skpro's API. | +| :control_knobs: **[API Reference]** | The detailed reference for skpro's API. | +| :hammer_and_wrench: **[Changelog]** | Changes and version history. | +| :deciduous_tree: **[Roadmap]** | skpro's software and community development plan. | +| :pencil: **[Related Software]** | A list of related software. | + +[tutorials]: https://skpro.readthedocs.io/en/latest/tutorials.html +[binder notebooks]: https://mybinder.org/v2/gh/sktime/skpro/main?filepath=examples +[user guides]: https://skpro.readthedocs.io/en/latest/user_guide.html +[extension templates]: https://github.com/sktime/skpro/tree/main/extension_templates +[api reference]: https://skpro.readthedocs.io/en/latest/api_reference.html +[changelog]: https://skpro.readthedocs.io/en/latest/changelog.html +[roadmap]: https://skpro.readthedocs.io/en/latest/roadmap.html +[related software]: https://skpro.readthedocs.io/en/latest/related_software.html + + +## :speech_balloon: Where to ask questions + +Questions and feedback are extremely welcome! +We strongly believe in the value of sharing help publicly, as it allows a wider audience to benefit from it. + +`skpro` is maintained by the `sktime` community, we use the same social channels. + +| Type | Platforms | +| ------------------------------- | --------------------------------------- | +| :bug: **Bug Reports** | [GitHub Issue Tracker] | +| :sparkles: **Feature Requests & Ideas** | [GitHub Issue Tracker] | +| :woman_technologist: **Usage Questions** | [GitHub Discussions] · [Stack Overflow] | +| :speech_balloon: **General Discussion** | [GitHub Discussions] | +| :factory: **Contribution & Development** | `dev-chat` channel · [Discord] | +| :globe_with_meridians: **Community collaboration session** | [Discord] - Fridays 3 pm UTC, dev/meet-ups channel | + +[github issue tracker]: https://github.com/sktime/skpro/issues +[github discussions]: https://github.com/sktime/skpro/discussions +[stack overflow]: https://stackoverflow.com/questions/tagged/sktime +[discord]: https://discord.com/invite/54ACzaFsn7 + +## :hourglass_flowing_sand: Installing `skpro` + +To install `skpro`, use `pip`: + +```bash +pip install skpro +``` + +or, with maximum dependencies, + +```bash +pip install skpro[all_extras] +``` + +Releases are available as source packages and binary wheels. You can see all available wheels [here](https://pypi.org/simple/skpro/). + +## :zap: Quickstart + +### Making probabilistic predictions + +``` python +from sklearn.datasets import load_diabetes +from sklearn.ensemble import RandomForestRegressor +from sklearn.linear_model import LinearRegression +from sklearn.model_selection import train_test_split + +from skpro.regression.residual import ResidualDouble + +# step 1: data specification +X, y = load_diabetes(return_X_y=True, as_frame=True) +X_train, X_new, y_train, _ = train_test_split(X, y) + +# step 2: specifying the regressor - any compatible regressor is valid! +# example - "squaring residuals" regressor +# random forest for mean prediction +# linear regression for variance prediction +reg_mean = RandomForestRegressor() +reg_resid = LinearRegression() +reg_proba = ResidualDouble(reg_mean, reg_resid) + +# step 3: fitting the model to training data +reg_proba.fit(X_train, y_train) + +# step 4: predicting labels on new data + +# probabilistic prediction modes - pick any or multiple + +# full distribution prediction +y_pred_proba = reg_proba.predict_proba(X_new) + +# interval prediction +y_pred_interval = reg_proba.predict_interval(X_new, coverage=0.9) + +# quantile prediction +y_pred_quantiles = reg_proba.predict_quantiles(X_new, alpha=[0.05, 0.5, 0.95]) -

- PyPI version - Build Status - License -

+# variance prediction +y_pred_var = reg_proba.predict_var(X_new) -A supervised domain-agnostic framework that allows for probabilistic modelling, namely the prediction of probability distributions for individual data points. +# mean prediction is same as "classical" sklearn predict, also available +y_pred_mean = reg_proba.predict(X_new) +``` -The package offers a variety of features and specifically allows for +### Evaluating predictions -- the implementation of probabilistic prediction strategies in the supervised contexts -- comparison of frequentist and Bayesian prediction methods -- strategy optimization through hyperparamter tuning and ensemble methods (e.g. bagging) -- workflow automation +``` python +# step 5: specifying evaluation metric +from skpro.metrics import CRPS -List of [developers and contributors](AUTHORS.rst) +metric = CRPS() # continuous rank probability score - any skpro metric works! -### Documentation +# step 6: evaluat metric, compare predictions to actuals +metric(y_test, y_pred_proba) +>>> 32.19 +``` -The full documentation is [available here](https://alan-turing-institute.github.io/skpro/). +## :wave: How to get involved -### Installation +There are many ways to get involved with development of `skpro`, which is +developed by the `sktime` community. +We follow the [all-contributors](https://github.com/all-contributors/all-contributors) +specification: all kinds of contributions are welcome - not just code. -Installation is easy using Python's package manager +| Documentation | | +| -------------------------- | -------------------------------------------------------------- | +| :gift_heart: **[Contribute]** | How to contribute to skpro. | +| :school_satchel: **[Mentoring]** | New to open source? Apply to our mentoring program! | +| :date: **[Meetings]** | Join our discussions, tutorials, workshops, and sprints! | +| :woman_mechanic: **[Developer Guides]** | How to further develop the skpro code base. | +| :medal_sports: **[Contributors]** | A list of all contributors. | +| :raising_hand: **[Roles]** | An overview of our core community roles. | +| :money_with_wings: **[Donate]** | Fund sktime and skpro maintenance and development. | +| :classical_building: **[Governance]** | How and by whom decisions are made in sktime's community. | - $ pip install skpro +[contribute]: https://skpro.readthedocs.io/en/latest/get_involved/contributing.html +[donate]: https://opencollective.com/sktime +[developer guides]: https://skpro.readthedocs.io/en/latest/developer_guide.html +[contributors]: https://github.com/sktime/skpro/blob/main/CONTRIBUTORS.md +[governance]: https://www.sktime.net/en/latest/get_involved/governance.html +[mentoring]: https://github.com/sktime/mentoring +[meetings]: https://calendar.google.com/calendar/u/0/embed?src=sktime.toolbox@gmail.com&ctz=UTC +[roles]: https://www.sktime.net/en/latest/about/team.html -### Contributing & Citation -We welcome contributions to the skpro project. Please read our [contribution guide](/CONTRIBUTING.md). +## :wave: Citation -If you use skpro in a scientific publication, we would appreciate [citations](CITATION.rst). +To cite `skpro`` in a scientific publication, see [citations](CITATION.rst).