From 28701df0afe4b3ee4ffa2c390cae6e8dead24769 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Wed, 27 Dec 2023 21:28:52 +0100 Subject: [PATCH 01/49] Creating a jupyter book Signed-off-by: miguelgfierro --- docs/Makefile | 19 --- docs/README.md | 15 +-- docs/_config.yml | 32 +++++ docs/_toc.yml | 9 ++ docs/intro.md | 11 ++ docs/markdown-notebooks.md | 53 ++++++++ docs/markdown.md | 55 ++++++++ docs/notebooks.ipynb | 122 +++++++++++++++++ docs/references.bib | 56 ++++++++ docs/requirements-doc.txt | 4 + docs/source/conf.py | 245 ---------------------------------- docs/source/datasets.rst | 152 --------------------- docs/source/evaluation.rst | 16 --- docs/source/index.rst | 26 ---- docs/source/models.rst | 264 ------------------------------------- docs/source/tuning.rst | 11 -- docs/source/utils.rst | 70 ---------- 17 files changed, 346 insertions(+), 814 deletions(-) delete mode 100644 docs/Makefile create mode 100644 docs/_config.yml create mode 100644 docs/_toc.yml create mode 100644 docs/intro.md create mode 100644 docs/markdown-notebooks.md create mode 100644 docs/markdown.md create mode 100644 docs/notebooks.ipynb create mode 100644 docs/references.bib create mode 100644 docs/requirements-doc.txt delete mode 100644 docs/source/conf.py delete mode 100644 docs/source/datasets.rst delete mode 100644 docs/source/evaluation.rst delete mode 100644 docs/source/index.rst delete mode 100644 docs/source/models.rst delete mode 100644 docs/source/tuning.rst delete mode 100644 docs/source/utils.rst diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 2fe93422bd..0000000000 --- a/docs/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# Copyright (c) Recommenders contributors. -# Licensed under the MIT License. - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 4f4a6b2b90..cee3e8a5e3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,18 +1,11 @@ # Documentation -To setup the documentation, first you need to install the dependencies of the full environment. For it please follow the [SETUP.md](../SETUP.md). Then type: +To setup the documentation, first you need to install the dependencies of the full environment. For it please follow the [SETUP.md](../SETUP.md). Then type from the root folder of the repository: - conda create -n reco_full -c conda-forge python=3.7 cudatoolkit=11.2 cudnn=8.1 - conda activate reco_full + pip install -r docs/requirements-doc.txt - pip install numpy - pip install "pymanopt@https://github.com/pymanopt/pymanopt/archive/fb36a272cdeecb21992cfd9271eb82baafeb316d.zip" - pip install sphinx_rtd_theme +To build the documentation: - -To build the documentation as HTML: - - cd docs - make html + jupyter-book build docs To contribute to this repository, please follow our [coding guidelines](https://github.com/Microsoft/Recommenders/wiki/Coding-Guidelines). See also the [reStructuredText documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) for the syntax of docstrings. diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000000..5f534f8051 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,32 @@ +# Book settings +# Learn more at https://jupyterbook.org/customize/config.html + +title: My sample book +author: The Jupyter Book Community +logo: logo.png + +# Force re-execution of notebooks on each build. +# See https://jupyterbook.org/content/execute.html +execute: + execute_notebooks: force + +# Define the name of the latex output file for PDF builds +latex: + latex_documents: + targetname: book.tex + +# Add a bibtex file so that we can create citations +bibtex_bibfiles: + - references.bib + +# Information about where the book exists on the web +repository: + url: https://github.com/executablebooks/jupyter-book # Online location of your book + path_to_book: docs # Optional path to your book, relative to the repository root + branch: master # Which branch of the repository should be used when creating links (optional) + +# Add GitHub buttons to your book +# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository +html: + use_issues_button: true + use_repository_button: true diff --git a/docs/_toc.yml b/docs/_toc.yml new file mode 100644 index 0000000000..74d5c7101e --- /dev/null +++ b/docs/_toc.yml @@ -0,0 +1,9 @@ +# Table of contents +# Learn more at https://jupyterbook.org/customize/toc.html + +format: jb-book +root: intro +chapters: +- file: markdown +- file: notebooks +- file: markdown-notebooks diff --git a/docs/intro.md b/docs/intro.md new file mode 100644 index 0000000000..f8cdc73cb2 --- /dev/null +++ b/docs/intro.md @@ -0,0 +1,11 @@ +# Welcome to your Jupyter Book + +This is a small sample book to give you a feel for how book content is +structured. +It shows off a few of the major file types, as well as some sample content. +It does not go in-depth into any particular topic - check out [the Jupyter Book documentation](https://jupyterbook.org) for more information. + +Check out the content pages bundled with this sample book to see more. + +```{tableofcontents} +``` diff --git a/docs/markdown-notebooks.md b/docs/markdown-notebooks.md new file mode 100644 index 0000000000..a057a320dc --- /dev/null +++ b/docs/markdown-notebooks.md @@ -0,0 +1,53 @@ +--- +jupytext: + formats: md:myst + text_representation: + extension: .md + format_name: myst + format_version: 0.13 + jupytext_version: 1.11.5 +kernelspec: + display_name: Python 3 + language: python + name: python3 +--- + +# Notebooks with MyST Markdown + +Jupyter Book also lets you write text-based notebooks using MyST Markdown. +See [the Notebooks with MyST Markdown documentation](https://jupyterbook.org/file-types/myst-notebooks.html) for more detailed instructions. +This page shows off a notebook written in MyST Markdown. + +## An example cell + +With MyST Markdown, you can define code cells with a directive like so: + +```{code-cell} +print(2 + 2) +``` + +When your book is built, the contents of any `{code-cell}` blocks will be +executed with your default Jupyter kernel, and their outputs will be displayed +in-line with the rest of your content. + +```{seealso} +Jupyter Book uses [Jupytext](https://jupytext.readthedocs.io/en/latest/) to convert text-based files to notebooks, and can support [many other text-based notebook files](https://jupyterbook.org/file-types/jupytext.html). +``` + +## Create a notebook with MyST Markdown + +MyST Markdown notebooks are defined by two things: + +1. YAML metadata that is needed to understand if / how it should convert text files to notebooks (including information about the kernel needed). + See the YAML at the top of this page for example. +2. The presence of `{code-cell}` directives, which will be executed with your book. + +That's all that is needed to get started! + +## Quickly add YAML metadata for MyST Notebooks + +If you have a markdown file and you'd like to quickly add YAML metadata to it, so that Jupyter Book will treat it as a MyST Markdown Notebook, run the following command: + +``` +jupyter-book myst init path/to/markdownfile.md +``` diff --git a/docs/markdown.md b/docs/markdown.md new file mode 100644 index 0000000000..0ddaab3fb6 --- /dev/null +++ b/docs/markdown.md @@ -0,0 +1,55 @@ +# Markdown Files + +Whether you write your book's content in Jupyter Notebooks (`.ipynb`) or +in regular markdown files (`.md`), you'll write in the same flavor of markdown +called **MyST Markdown**. +This is a simple file to help you get started and show off some syntax. + +## What is MyST? + +MyST stands for "Markedly Structured Text". It +is a slight variation on a flavor of markdown called "CommonMark" markdown, +with small syntax extensions to allow you to write **roles** and **directives** +in the Sphinx ecosystem. + +For more about MyST, see [the MyST Markdown Overview](https://jupyterbook.org/content/myst.html). + +## Sample Roles and Directives + +Roles and directives are two of the most powerful tools in Jupyter Book. They +are kind of like functions, but written in a markup language. They both +serve a similar purpose, but **roles are written in one line**, whereas +**directives span many lines**. They both accept different kinds of inputs, +and what they do with those inputs depends on the specific role or directive +that is being called. + +Here is a "note" directive: + +```{note} +Here is a note +``` + +It will be rendered in a special box when you build your book. + +Here is an inline directive to refer to a document: {doc}`markdown-notebooks`. + + +## Citations + +You can also cite references that are stored in a `bibtex` file. For example, +the following syntax: `` {cite}`holdgraf_evidence_2014` `` will render like +this: {cite}`holdgraf_evidence_2014`. + +Moreover, you can insert a bibliography into your page with this syntax: +The `{bibliography}` directive must be used for all the `{cite}` roles to +render properly. +For example, if the references for your book are stored in `references.bib`, +then the bibliography is inserted with: + +```{bibliography} +``` + +## Learn more + +This is just a simple starter to get you started. +You can learn a lot more at [jupyterbook.org](https://jupyterbook.org). diff --git a/docs/notebooks.ipynb b/docs/notebooks.ipynb new file mode 100644 index 0000000000..fdb7176c42 --- /dev/null +++ b/docs/notebooks.ipynb @@ -0,0 +1,122 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Content with notebooks\n", + "\n", + "You can also create content with Jupyter Notebooks. This means that you can include\n", + "code blocks and their outputs in your book.\n", + "\n", + "## Markdown + notebooks\n", + "\n", + "As it is markdown, you can embed images, HTML, etc into your posts!\n", + "\n", + "![](https://myst-parser.readthedocs.io/en/latest/_static/logo-wide.svg)\n", + "\n", + "You can also $add_{math}$ and\n", + "\n", + "$$\n", + "math^{blocks}\n", + "$$\n", + "\n", + "or\n", + "\n", + "$$\n", + "\\begin{aligned}\n", + "\\mbox{mean} la_{tex} \\\\ \\\\\n", + "math blocks\n", + "\\end{aligned}\n", + "$$\n", + "\n", + "But make sure you \\$Escape \\$your \\$dollar signs \\$you want to keep!\n", + "\n", + "## MyST markdown\n", + "\n", + "MyST markdown works in Jupyter Notebooks as well. For more information about MyST markdown, check\n", + "out [the MyST guide in Jupyter Book](https://jupyterbook.org/content/myst.html),\n", + "or see [the MyST markdown documentation](https://myst-parser.readthedocs.io/en/latest/).\n", + "\n", + "## Code blocks and outputs\n", + "\n", + "Jupyter Book will also embed your code blocks and output in your book.\n", + "For example, here's some sample Matplotlib code:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from matplotlib import rcParams, cycler\n", + "import matplotlib.pyplot as plt\n", + "import numpy as np\n", + "plt.ion()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Fixing random state for reproducibility\n", + "np.random.seed(19680801)\n", + "\n", + "N = 10\n", + "data = [np.logspace(0, 1, 100) + np.random.randn(100) + ii for ii in range(N)]\n", + "data = np.array(data).T\n", + "cmap = plt.cm.coolwarm\n", + "rcParams['axes.prop_cycle'] = cycler(color=cmap(np.linspace(0, 1, N)))\n", + "\n", + "\n", + "from matplotlib.lines import Line2D\n", + "custom_lines = [Line2D([0], [0], color=cmap(0.), lw=4),\n", + " Line2D([0], [0], color=cmap(.5), lw=4),\n", + " Line2D([0], [0], color=cmap(1.), lw=4)]\n", + "\n", + "fig, ax = plt.subplots(figsize=(10, 5))\n", + "lines = ax.plot(data)\n", + "ax.legend(custom_lines, ['Cold', 'Medium', 'Hot']);" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "There is a lot more that you can do with outputs (such as including interactive outputs)\n", + "with your book. For more information about this, see [the Jupyter Book documentation](https://jupyterbook.org)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.0" + }, + "widgets": { + "application/vnd.jupyter.widget-state+json": { + "state": {}, + "version_major": 2, + "version_minor": 0 + } + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/references.bib b/docs/references.bib new file mode 100644 index 0000000000..783ec6aa5a --- /dev/null +++ b/docs/references.bib @@ -0,0 +1,56 @@ +--- +--- + +@inproceedings{holdgraf_evidence_2014, + address = {Brisbane, Australia, Australia}, + title = {Evidence for {Predictive} {Coding} in {Human} {Auditory} {Cortex}}, + booktitle = {International {Conference} on {Cognitive} {Neuroscience}}, + publisher = {Frontiers in Neuroscience}, + author = {Holdgraf, Christopher Ramsay and de Heer, Wendy and Pasley, Brian N. and Knight, Robert T.}, + year = {2014} +} + +@article{holdgraf_rapid_2016, + title = {Rapid tuning shifts in human auditory cortex enhance speech intelligibility}, + volume = {7}, + issn = {2041-1723}, + url = {http://www.nature.com/doifinder/10.1038/ncomms13654}, + doi = {10.1038/ncomms13654}, + number = {May}, + journal = {Nature Communications}, + author = {Holdgraf, Christopher Ramsay and de Heer, Wendy and Pasley, Brian N. and Rieger, Jochem W. and Crone, Nathan and Lin, Jack J. and Knight, Robert T. and Theunissen, Frédéric E.}, + year = {2016}, + pages = {13654}, + file = {Holdgraf et al. - 2016 - Rapid tuning shifts in human auditory cortex enhance speech intelligibility.pdf:C\:\\Users\\chold\\Zotero\\storage\\MDQP3JWE\\Holdgraf et al. - 2016 - Rapid tuning shifts in human auditory cortex enhance speech intelligibility.pdf:application/pdf} +} + +@inproceedings{holdgraf_portable_2017, + title = {Portable learning environments for hands-on computational instruction using container-and cloud-based technology to teach data science}, + volume = {Part F1287}, + isbn = {978-1-4503-5272-7}, + doi = {10.1145/3093338.3093370}, + abstract = {© 2017 ACM. There is an increasing interest in learning outside of the traditional classroom setting. This is especially true for topics covering computational tools and data science, as both are challenging to incorporate in the standard curriculum. These atypical learning environments offer new opportunities for teaching, particularly when it comes to combining conceptual knowledge with hands-on experience/expertise with methods and skills. Advances in cloud computing and containerized environments provide an attractive opportunity to improve the effciency and ease with which students can learn. This manuscript details recent advances towards using commonly-Available cloud computing services and advanced cyberinfrastructure support for improving the learning experience in bootcamp-style events. We cover the benets (and challenges) of using a server hosted remotely instead of relying on student laptops, discuss the technology that was used in order to make this possible, and give suggestions for how others could implement and improve upon this model for pedagogy and reproducibility.}, + booktitle = {{ACM} {International} {Conference} {Proceeding} {Series}}, + author = {Holdgraf, Christopher Ramsay and Culich, A. and Rokem, A. and Deniz, F. and Alegro, M. and Ushizima, D.}, + year = {2017}, + keywords = {Teaching, Bootcamps, Cloud computing, Data science, Docker, Pedagogy} +} + +@article{holdgraf_encoding_2017, + title = {Encoding and decoding models in cognitive electrophysiology}, + volume = {11}, + issn = {16625137}, + doi = {10.3389/fnsys.2017.00061}, + abstract = {© 2017 Holdgraf, Rieger, Micheli, Martin, Knight and Theunissen. Cognitive neuroscience has seen rapid growth in the size and complexity of data recorded from the human brain as well as in the computational tools available to analyze this data. This data explosion has resulted in an increased use of multivariate, model-based methods for asking neuroscience questions, allowing scientists to investigate multiple hypotheses with a single dataset, to use complex, time-varying stimuli, and to study the human brain under more naturalistic conditions. These tools come in the form of “Encoding” models, in which stimulus features are used to model brain activity, and “Decoding” models, in which neural features are used to generated a stimulus output. Here we review the current state of encoding and decoding models in cognitive electrophysiology and provide a practical guide toward conducting experiments and analyses in this emerging field. Our examples focus on using linear models in the study of human language and audition. We show how to calculate auditory receptive fields from natural sounds as well as how to decode neural recordings to predict speech. The paper aims to be a useful tutorial to these approaches, and a practical introduction to using machine learning and applied statistics to build models of neural activity. The data analytic approaches we discuss may also be applied to other sensory modalities, motor systems, and cognitive systems, and we cover some examples in these areas. In addition, a collection of Jupyter notebooks is publicly available as a complement to the material covered in this paper, providing code examples and tutorials for predictive modeling in python. The aimis to provide a practical understanding of predictivemodeling of human brain data and to propose best-practices in conducting these analyses.}, + journal = {Frontiers in Systems Neuroscience}, + author = {Holdgraf, Christopher Ramsay and Rieger, J.W. and Micheli, C. and Martin, S. and Knight, R.T. and Theunissen, F.E.}, + year = {2017}, + keywords = {Decoding models, Encoding models, Electrocorticography (ECoG), Electrophysiology/evoked potentials, Machine learning applied to neuroscience, Natural stimuli, Predictive modeling, Tutorials} +} + +@book{ruby, + title = {The Ruby Programming Language}, + author = {Flanagan, David and Matsumoto, Yukihiro}, + year = {2008}, + publisher = {O'Reilly Media} +} diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt new file mode 100644 index 0000000000..2428eec0d3 --- /dev/null +++ b/docs/requirements-doc.txt @@ -0,0 +1,4 @@ +jupyter-book +sphinx +sphinx_inline_tabs +ghp-import \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index caed50ab7b..0000000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,245 +0,0 @@ -# Copyright (c) Recommenders contributors. -# Licensed under the MIT License. - -# -*- coding: utf-8 -*- -# -# Configuration file for the Sphinx documentation builder. -# -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/master/config - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys - -sys.path.insert(0, os.path.abspath(os.path.join("..", ".."))) -sys.setrecursionlimit(1500) - -from recommenders import TITLE, VERSION, COPYRIGHT, AUTHOR - -# -- Project information ----------------------------------------------------- - -project = TITLE -copyright = COPYRIGHT -author = AUTHOR - -# The short X.Y version -version = VERSION -# The full version, including alpha/beta/rc tags -release = VERSION - - -# -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.doctest", - "sphinx.ext.intersphinx", - "sphinx.ext.ifconfig", - "sphinx.ext.viewcode", # Add links to highlighted source code - "sphinx.ext.napoleon", # to render Google format docstrings -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = ".rst" - -# The master toctree document. -master_doc = "index" - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["Thumbs.db", ".DS_Store"] - - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = None - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ["images"] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - - -# -- Options for HTMLHelp output --------------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = "Recommendersdoc" - - -# -- Options for LaTeX output ------------------------------------------------ - -latex_elements = { - "papersize": "letterpaper", - "pointsize": "10pt", - "figure_align": "htbp", - "preamble": r""" - %% Adding source listings https://en.wikibooks.org/wiki/LaTeX/Source_Code_Listings - \usepackage{listings} - \usepackage{color} - - \definecolor{mygreen}{rgb}{0,0.6,0} - \definecolor{mygray}{rgb}{0.5,0.5,0.5} - \definecolor{mymauve}{rgb}{0.58,0,0.82} - - \lstset{ - backgroundcolor=\color{white}, % choose the background color; you must add \usepackage{color} or \usepackage{xcolor}; should come as last argument - basicstyle=\footnotesize, % the size of the fonts that are used for the code - breakatwhitespace=false, % sets if automatic breaks should only happen at whitespace - breaklines=true, % sets automatic line breaking - captionpos=b, % sets the caption-position to bottom - commentstyle=\color{mygreen}, % comment style - deletekeywords={...}, % if you want to delete keywords from the given language - escapeinside={\%*}{*)}, % if you want to add LaTeX within your code - extendedchars=true, % lets you use non-ASCII characters; for 8-bits encodings only, does not work with UTF-8 - firstnumber=1000, % start line enumeration with line 1000 - frame=single, % adds a frame around the code - keepspaces=true, % keeps spaces in text, useful for keeping indentation of code (possibly needs columns=flexible) - keywordstyle=\color{blue}, % keyword style - language=Python, % the language of the code - morekeywords={*,...}, % if you want to add more keywords to the set - numbers=left, % where to put the line-numbers; possible values are (none, left, right) - numbersep=5pt, % how far the line-numbers are from the code - numberstyle=\tiny\color{mygray}, % the style that is used for the line-numbers - rulecolor=\color{black}, % if not set, the frame-color may be changed on line-breaks within not-black text (e.g. comments (green here)) - showspaces=false, % show spaces everywhere adding particular underscores; it overrides 'showstringspaces' - showstringspaces=false, % underline spaces within strings only - showtabs=false, % show tabs within strings adding particular underscores - stepnumber=2, % the step between two line-numbers. If it's 1, each line will be numbered - stringstyle=\color{mymauve}, % string literal style - tabsize=2, % sets default tabsize to 2 spaces - title=\lstname % show the filename of files included with \lstinputlisting; also try caption instead of title - } - - """, -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - ( - master_doc, - "Recommenders.tex", - "Recommenders Documentation", - "Recommenders", - "manual", - ) -] - - -# -- Options for manual page output ------------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [(master_doc, "recommenders", "Recommenders Documentation", [author], 1)] - - -# -- Options for Texinfo output ---------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - master_doc, - "Recommenders", - "Recommenders Documentation", - author, - "Recommenders", - "One line description of project.", - "Miscellaneous", - ) -] - - -# -- Options for Epub output ------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -# -# epub_identifier = '' - -# A unique identification for the text. -# -# epub_uid = '' - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ["search.html"] - - -# -- Extension configuration ------------------------------------------------- - -# -- Options for intersphinx extension --------------------------------------- - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"https://docs.python.org/": None} - -################################################## -# Other options -# html_favicon = os.path.join(html_static_path[0], "favicon.ico") - - -# Ensure that __init__() is always documented -# source: https://stackoverflow.com/a/5599712 -def skip(app, what, name, obj, would_skip, options): - if name == "__init__": - return False - return would_skip - - -def setup(app): - app.connect("autodoc-skip-member", skip) diff --git a/docs/source/datasets.rst b/docs/source/datasets.rst deleted file mode 100644 index 9cc88735ff..0000000000 --- a/docs/source/datasets.rst +++ /dev/null @@ -1,152 +0,0 @@ -.. _dataset: - -Dataset module -############## - -Recommendation datasets and related utilities - -Recommendation datasets -*********************** - -Amazon Reviews -============== - -`Amazon Reviews dataset `_ consists of reviews from Amazon. -The data span a period of 18 years, including ~35 million reviews up to March 2013. Reviews include product and user -information, ratings, and a plaintext review. - -:Citation: - - J. McAuley and J. Leskovec, "Hidden factors and hidden topics: understanding rating dimensions with review text", - RecSys, 2013. - -.. automodule:: recommenders.datasets.amazon_reviews - :members: - -CORD-19 -======= - -`COVID-19 Open Research Dataset (CORD-19) `_ is a full-text -and metadata dataset of COVID-19 and coronavirus-related scholarly articles optimized -for machine readability and made available for use by the global research community. - -In response to the COVID-19 pandemic, the Allen Institute for AI has partnered with leading research groups -to prepare and distribute the COVID-19 Open Research Dataset (CORD-19), a free resource of -over 47,000 scholarly articles, including over 36,000 with full text, about COVID-19 and the -coronavirus family of viruses for use by the global research community. - -This dataset is intended to mobilize researchers to apply recent advances in natural language processing -to generate new insights in support of the fight against this infectious disease. - -:Citation: - - Wang, L.L., Lo, K., Chandrasekhar, Y., Reas, R., Yang, J., Eide, D., - Funk, K., Kinney, R., Liu, Z., Merrill, W. and Mooney, P. "Cord-19: The COVID-19 Open Research Dataset.", 2020. - - -.. automodule:: recommenders.datasets.covid_utils - :members: - -Criteo -====== - -`Criteo dataset `_, released by Criteo Labs, is an online advertising dataset that contains feature values and click feedback -for millions of display Ads. Every Ad has has 40 attributes, the first attribute is the label where a value 1 represents -that the Ad has been clicked on and a 0 represents it wasn't clicked on. The rest consist of 13 integer columns and -26 categorical columns. - -.. automodule:: recommenders.datasets.criteo - :members: - -MIND -==== - -`MIcrosoft News Dataset (MIND) `_, is a large-scale dataset for news recommendation research. It was collected from -anonymized behavior logs of Microsoft News website. - -MIND contains about 160k English news articles and more than 15 million impression logs generated by 1 million users. -Every news article contains rich textual content including title, abstract, body, category and entities. -Each impression log contains the click events, non-clicked events and historical news click behaviors of this user before -this impression. To protect user privacy, each user was de-linked from the production system when securely hashed into an anonymized ID. - -:Citation: - - Fangzhao Wu, Ying Qiao, Jiun-Hung Chen, Chuhan Wu, Tao Qi, Jianxun Lian, Danyang Liu, Xing Xie, Jianfeng Gao, Winnie Wu - and Ming Zhou, "MIND: A Large-scale Dataset for News Recommendation", ACL, 2020. - - - -.. automodule:: recommenders.datasets.mind - :members: - -MovieLens -========= - -The `MovieLens datasets `_, first released in 1998, -describe people's expressed preferences -for movies. These preferences take the form of `` tuples, -each the result of a person expressing a preference (a 0-5 star rating) for a movie -at a particular time. - -It comes with several sizes: - -* MovieLens 100k: 100,000 ratings from 1000 users on 1700 movies. -* MovieLens 1M: 1 million ratings from 6000 users on 4000 movies. -* MovieLens 10M: 10 million ratings from 72000 users on 10000 movies. -* MovieLens 20M: 20 million ratings from 138000 users on 27000 movies - -:Citation: - - F. M. Harper and J. A. Konstan. "The MovieLens Datasets: History and Context". - ACM Transactions on Interactive Intelligent Systems (TiiS) 5, 4, Article 19, - DOI=http://dx.doi.org/10.1145/2827872, 2015. - -.. automodule:: recommenders.datasets.movielens - :members: - -Download utilities -****************** - -.. automodule:: recommenders.datasets.download_utils - :members: - - -Cosmos CLI utilities -********************* - -.. automodule:: recommenders.datasets.cosmos_cli - :members: - - -Pandas dataframe utilities -*************************** - -.. automodule:: recommenders.datasets.pandas_df_utils - :members: - - -Splitter utilities -****************** - -.. automodule:: recommenders.datasets.python_splitters - :members: - -.. automodule:: recommenders.datasets.spark_splitters - :members: - -.. automodule:: recommenders.datasets.split_utils - :members: - - -Sparse utilities -**************** - -.. automodule:: recommenders.datasets.sparse - :members: - - -Knowledge graph utilities -************************* - -.. automodule:: recommenders.datasets.wikidata - :members: diff --git a/docs/source/evaluation.rst b/docs/source/evaluation.rst deleted file mode 100644 index 21fba4f7bf..0000000000 --- a/docs/source/evaluation.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _evaluation: - -Evaluation module -************************** - -Python evaluation -=============================== - -.. automodule:: recommenders.evaluation.python_evaluation - :members: - -PySpark evaluation -=============================== - -.. automodule:: recommenders.evaluation.spark_evaluation - :members: \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 624d2cf63d..0000000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,26 +0,0 @@ - -Recommender Utilities -=================================================== - -The `Recommenders repository `_ provides examples and best practices for building recommendation systems, provided as Jupyter notebooks. - -The module `recommenders `_ contains functions to simplify common tasks used when developing and -evaluating recommender systems. - -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - Utils - Datasets - Evaluation - Recommender algorithms - Hyperparameter tuning - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/source/models.rst b/docs/source/models.rst deleted file mode 100644 index 4b5080869c..0000000000 --- a/docs/source/models.rst +++ /dev/null @@ -1,264 +0,0 @@ -.. _recommender: - -Recommender algorithms module -############################## - -Recommender system algorithms and utilities. - -Cornac -****************************** - -.. automodule:: recommenders.models.cornac.cornac_utils - :members: - -DeepRec -****************************** - -Base model -================== -.. automodule:: recommenders.models.deeprec.models.base_model - :members: - -DKN -================== -.. automodule:: recommenders.models.deeprec.models.dkn - :members: - -DKN item-to-item -================== -.. automodule:: recommenders.models.deeprec.models.dkn_item2item - :members: - -LightGCN -================== -.. automodule:: recommenders.models.deeprec.models.graphrec.lightgcn - :members: - -xDeepFM -============== -.. automodule:: recommenders.models.deeprec.models.xDeepFM - :members: - -Sequential models -================== - -Sequential base model ---------------------------- -.. automodule:: recommenders.models.deeprec.models.sequential.sequential_base_model - :members: - -A2SVD -------------- -.. automodule:: recommenders.models.deeprec.models.sequential.asvd - :members: - -Caser ----------------- -.. automodule:: recommenders.models.deeprec.models.sequential.caser - :members: - -GRU --------------- -.. automodule:: recommenders.models.deeprec.models.sequential.gru - :members: - -NextItNet --------------- -.. automodule:: recommenders.models.deeprec.models.sequential.nextitnet - :members: - -RNN Cells ------------- -.. automodule:: recommenders.models.deeprec.models.sequential.rnn_cell_implement - :members: - -SUM -------------------------- -.. automodule:: recommenders.models.deeprec.models.sequential.sum - :members: - -.. automodule:: recommenders.models.deeprec.models.sequential.sum_cells - :members: - -SLIRec -------------- -.. automodule:: recommenders.models.deeprec.models.sequential.sli_rec - :members: - -Iterators -=========== - -.. automodule:: recommenders.models.deeprec.io.iterator - :members: - -.. automodule:: recommenders.models.deeprec.io.dkn_iterator - :members: - -.. automodule:: recommenders.models.deeprec.io.dkn_item2item_iterator - :members: - -.. automodule:: recommenders.models.deeprec.io.nextitnet_iterator - :members: - -.. automodule:: recommenders.models.deeprec.io.sequential_iterator - :members: - -Data processing utilities -=========================== - -.. automodule:: recommenders.models.deeprec.DataModel.ImplicitCF - :members: - -Utilities -============ - -.. automodule:: recommenders.models.deeprec.deeprec_utils - :members: - -FastAI -****************************** - -.. automodule:: recommenders.models.fastai.fastai_utils - :members: - -GeoIMC -****************************** - -.. automodule:: recommenders.models.geoimc.geoimc_algorithm - :members: - -.. automodule:: recommenders.models.geoimc.geoimc_data - :members: - -.. automodule:: recommenders.models.geoimc.geoimc_predict - :members: - -.. automodule:: recommenders.models.geoimc.geoimc_utils - :members: - -LightFM -****************************** - -.. automodule:: recommenders.models.lightfm.lightfm_utils - :members: - -LightGBM -****************************** - -.. automodule:: recommenders.models.lightgbm.lightgbm_utils - :members: - -NCF -****************************** - -.. automodule:: recommenders.models.ncf.dataset - :members: - -.. automodule:: recommenders.models.ncf.ncf_singlenode - :members: - -NewsRec -****************************** - -.. automodule:: recommenders.models.newsrec.io.mind_all_iterator - :members: - -.. automodule:: recommenders.models.newsrec.io.mind_iterator - :members: - -.. automodule:: recommenders.models.newsrec.models.base_model - :members: - -.. automodule:: recommenders.models.newsrec.models.layers - :members: - -.. automodule:: recommenders.models.newsrec.models.lstur - :members: - -.. automodule:: recommenders.models.newsrec.models.naml - :members: - -.. automodule:: recommenders.models.newsrec.models.npa - :members: - -.. automodule:: recommenders.models.newsrec.models.nrms - :members: - -.. automodule:: recommenders.models.newsrec.newsrec_utils - :members: - -RBM -****************************** - -.. automodule:: recommenders.models.rbm.rbm - :members: - - -RLRMC -****************************** - -.. automodule:: recommenders.models.rlrmc.RLRMCalgorithm - :members: - -.. automodule:: recommenders.models.rlrmc.RLRMCdataset - :members: - -.. automodule:: recommenders.models.rlrmc.conjugate_gradient_ms - :members: - - -SAR -****************************** - -.. automodule:: recommenders.models.sar.sar_singlenode - :members: - -SASRec -****************************** - -.. automodule:: recommenders.models.sasrec.model - :members: - -.. automodule:: recommenders.models.sasrec.sampler - :members: - -.. automodule:: recommenders.models.sasrec.util - :members: - - -SSE-PT -****************************** - -.. automodule:: recommenders.models.sasrec.ssept - :members: - - -Surprise -****************************** - -.. automodule:: recommenders.models.surprise.surprise_utils - :members: - - -TF-IDF -****************************** - -.. automodule:: recommenders.models.tfidf.tfidf_utils - :members: - - -VAE -****************************** - -.. automodule:: recommenders.models.vae.multinomial_vae - :members: - -.. automodule:: recommenders.models.vae.standard_vae - :members: - - -Wide & Deep -****************************** - -.. automodule:: recommenders.models.wide_deep.wide_deep_utils - :members: \ No newline at end of file diff --git a/docs/source/tuning.rst b/docs/source/tuning.rst deleted file mode 100644 index 24f0fab9bf..0000000000 --- a/docs/source/tuning.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _tuning: - -Hyperparameter tuning module -********************************* -Hyperparameter tuning module from Recommenders utilities. - -Parameter sweep utils -=============================== - -.. automodule:: recommenders.tuning.parameter_sweep - :members: \ No newline at end of file diff --git a/docs/source/utils.rst b/docs/source/utils.rst deleted file mode 100644 index b0f8b166e8..0000000000 --- a/docs/source/utils.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. _common: - -Common utilities module -************************** - - -General utilities -=============================== - -.. automodule:: recommenders.utils.general_utils - :members: - - -GPU utilities -=============================== - -.. automodule:: recommenders.utils.gpu_utils - :members: - - -Kubernetes utilities -=============================== - -.. automodule:: recommenders.utils.k8s_utils - :members: - - -Notebook utilities -=============================== - -.. automodule:: recommenders.utils.notebook_utils - :members: - -.. automodule:: recommenders.utils.notebook_memory_management - :members: - - -Python utilities -=============================== - -.. automodule:: recommenders.utils.python_utils - :members: - - -Spark utilities -=============================== - -.. automodule:: recommenders.utils.spark_utils - :members: - - -Tensorflow utilities -=============================== - -.. automodule:: recommenders.utils.tf_utils - :members: - - -Timer -=============================== - -.. automodule:: recommenders.utils.timer - :members: - - -Plot utilities -=============================== - -.. automodule:: recommenders.utils.plot - :members: \ No newline at end of file From 9474dff874773430384606710fe91a27c7ce4ff1 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Wed, 27 Dec 2023 21:50:13 +0100 Subject: [PATCH 02/49] Creating documentation Signed-off-by: miguelgfierro --- docs/README.md | 2 +- docs/_config.yml | 57 ++++++++++++++++++++++++---------------- recommenders/__init__.py | 2 +- setup.py | 2 +- 4 files changed, 38 insertions(+), 25 deletions(-) diff --git a/docs/README.md b/docs/README.md index cee3e8a5e3..9675bc7472 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,4 +8,4 @@ To build the documentation: jupyter-book build docs -To contribute to this repository, please follow our [coding guidelines](https://github.com/Microsoft/Recommenders/wiki/Coding-Guidelines). See also the [reStructuredText documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) for the syntax of docstrings. +To contribute to this repository, please follow our [coding guidelines](https://github.com/recommenders-team/recommenders/wiki/Coding-Guidelines). See also the [reStructuredText documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) for the syntax of docstrings. diff --git a/docs/_config.yml b/docs/_config.yml index 5f534f8051..1853c84206 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,32 +1,45 @@ # Book settings # Learn more at https://jupyterbook.org/customize/config.html -title: My sample book -author: The Jupyter Book Community -logo: logo.png +title: Recommenders documentation +author: Recommenders contributors +logo: https://raw.githubusercontent.com/recommenders-team/artwork/main/color/recommenders_color.svg -# Force re-execution of notebooks on each build. -# See https://jupyterbook.org/content/execute.html -execute: - execute_notebooks: force -# Define the name of the latex output file for PDF builds -latex: - latex_documents: - targetname: book.tex +# Short description about the book +description: >- + Recommenders - Python utilities for building recommendation systems + +execute: + execute_notebooks : off -# Add a bibtex file so that we can create citations -bibtex_bibfiles: - - references.bib +# Interact link settings +notebook_interface : "notebook" -# Information about where the book exists on the web +# Launch button settings repository: - url: https://github.com/executablebooks/jupyter-book # Online location of your book - path_to_book: docs # Optional path to your book, relative to the repository root - branch: master # Which branch of the repository should be used when creating links (optional) + url : https://github.com/recommenders-team/recommenders + path_to_book : docs + branch : main -# Add GitHub buttons to your book -# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository +launch_buttons: + notebook_interface : classic + +# HTML-specific settings html: - use_issues_button: true - use_repository_button: true + favicon : https://raw.githubusercontent.com/recommenders-team/artwork/main/icon/recommenders_color_icon.svg + home_page_in_navbar : false + use_repository_button : true + use_issues_button : true + baseurl : https://recommenders-team.github.io/recommenders/ + +sphinx: + extra_extensions: + - sphinx_inline_tabs + - sphinx.ext.autodoc + - sphinx.ext.napoleon + - sphinx.ext.viewcode + config: + napoleon_google_docstring: True + autodoc_member_order: groupwise + autoclass_content: both \ No newline at end of file diff --git a/recommenders/__init__.py b/recommenders/__init__.py index 75648c36e0..e28bf197ff 100644 --- a/recommenders/__init__.py +++ b/recommenders/__init__.py @@ -3,7 +3,7 @@ __title__ = "Recommenders" __version__ = "1.1.1" -__author__ = "RecoDev Team at Microsoft" +__author__ = "Recommenders contributors" __license__ = "MIT" __copyright__ = "Copyright 2018-present Recommenders contributors." diff --git a/setup.py b/setup.py index 3ce8b5d4bf..bb9db16883 100644 --- a/setup.py +++ b/setup.py @@ -95,7 +95,7 @@ setup( name="recommenders", version=version, - description="Recommenders - Python utilities for building recommender systems", + description="Recommenders - Python utilities for building recommendation systems", long_description=LONG_DESCRIPTION, long_description_content_type="text/markdown", url="https://github.com/recommenders-team/recommenders", From 6028199990ac8f6280ae8b65a1b378cd05d25f39 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 28 Dec 2023 12:09:13 +0100 Subject: [PATCH 03/49] :memo: Signed-off-by: miguelgfierro --- README.md | 8 ++++---- docs/intro.md | 28 ++++++++++++++++++++++------ 2 files changed, 26 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 36664f58c5..cb20b3b26b 100644 --- a/README.md +++ b/README.md @@ -25,10 +25,10 @@ Recommenders is a project under the [Linux Foundation of AI and Data](https://lf This repository contains examples and best practices for building recommendation systems, provided as Jupyter notebooks. The examples detail our learnings on five key tasks: -- [Prepare Data](examples/01_prepare_data): Preparing and loading data for each recommender algorithm. -- [Model](examples/00_quick_start): Building models using various classical and deep learning recommender algorithms such as Alternating Least Squares ([ALS](https://spark.apache.org/docs/latest/api/python/_modules/pyspark/ml/recommendation.html#ALS)) or eXtreme Deep Factorization Machines ([xDeepFM](https://arxiv.org/abs/1803.05170)). +- [Prepare Data](examples/01_prepare_data): Preparing and loading data for each recommendation algorithm. +- [Model](examples/00_quick_start): Building models using various classical and deep learning recommendation algorithms such as Alternating Least Squares ([ALS](https://spark.apache.org/docs/latest/api/python/_modules/pyspark/ml/recommendation.html#ALS)) or eXtreme Deep Factorization Machines ([xDeepFM](https://arxiv.org/abs/1803.05170)). - [Evaluate](examples/03_evaluate): Evaluating algorithms with offline metrics. -- [Model Select and Optimize](examples/04_model_select_and_optimize): Tuning and optimizing hyperparameters for recommender models. +- [Model Select and Optimize](examples/04_model_select_and_optimize): Tuning and optimizing hyperparameters for recommendation models. - [Operationalize](examples/05_operationalize): Operationalizing models in a production environment on Azure. Several utilities are provided in [recommenders](recommenders) to support common tasks such as loading datasets in the format expected by different algorithms, evaluating model outputs, and splitting training/test data. Implementations of several state-of-the-art algorithms are included for self-study and customization in your own applications. See the [Recommenders documentation](https://readthedocs.org/projects/microsoft-recommenders/). @@ -73,7 +73,7 @@ In addition to the core package, several extras are also provided, including: ## Algorithms -The table below lists the recommender algorithms currently available in the repository. Notebooks are linked under the Example column as Quick start, showcasing an easy to run example of the algorithm, or as Deep dive, explaining in detail the math and implementation of the algorithm. +The table below lists the recommendationalgorithms currently available in the repository. Notebooks are linked under the Example column as Quick start, showcasing an easy to run example of the algorithm, or as Deep dive, explaining in detail the math and implementation of the algorithm. | Algorithm | Type | Description | Example | |-----------|------|-------------|---------| diff --git a/docs/intro.md b/docs/intro.md index f8cdc73cb2..d06ab11e06 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -1,11 +1,27 @@ -# Welcome to your Jupyter Book +# Welcome to Recommenders -This is a small sample book to give you a feel for how book content is -structured. -It shows off a few of the major file types, as well as some sample content. -It does not go in-depth into any particular topic - check out [the Jupyter Book documentation](https://jupyterbook.org) for more information. +Recommenders objective is to assist researchers, developers and enthusiasts in prototyping, experimenting with and bringing to production a range of classic and state-of-the-art recommendation systems. -Check out the content pages bundled with this sample book to see more. +````{margin} +```sh +pip install recommenders +``` +Star Us +```` + +Recommenders is a project under the [Linux Foundation of AI and Data](https://lfaidata.foundation/projects/). + +This repository contains examples and best practices for building recommendation systems, provided as Jupyter notebooks. + +The examples detail our learnings on five key tasks: + +- Prepare Data: Preparing and loading data for each recommendation algorithm. +- Model: Building models using various classical and deep learning recommendation algorithms such as Alternating Least Squares ([ALS](https://spark.apache.org/docs/latest/api/python/_modules/pyspark/ml/recommendation.html#ALS)) or eXtreme Deep Factorization Machines ([xDeepFM](https://arxiv.org/abs/1803.05170)). +- Evaluate: Evaluating algorithms with offline metrics. +- Model Select and Optimize: Tuning and optimizing hyperparameters for recommendation models. +- Operationalize: Operationalizing models in a production environment on Azure. + +Several utilities are provided in the `recommenders` library to support common tasks such as loading datasets in the format expected by different algorithms, evaluating model outputs, and splitting training/test data. Implementations of several state-of-the-art algorithms are included for self-study and customization in your own applications. ```{tableofcontents} ``` From 9b95db36f843a5eafea3c8097d5d4ee35ae12312 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Fri, 29 Dec 2023 08:51:26 +0100 Subject: [PATCH 04/49] WIP Signed-off-by: miguelgfierro --- README.md | 2 +- docs/README.md | 11 ---- docs/_toc.yml | 10 +-- docs/intro.md | 2 + docs/markdown-notebooks.md | 53 ---------------- docs/markdown.md | 55 ----------------- docs/notebooks.ipynb | 122 ------------------------------------- docs/references.bib | 56 ----------------- 8 files changed, 9 insertions(+), 302 deletions(-) delete mode 100644 docs/README.md delete mode 100644 docs/markdown-notebooks.md delete mode 100644 docs/markdown.md delete mode 100644 docs/notebooks.ipynb delete mode 100644 docs/references.bib diff --git a/README.md b/README.md index cb20b3b26b..b67c1f1582 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ In addition to the core package, several extras are also provided, including: ## Algorithms -The table below lists the recommendationalgorithms currently available in the repository. Notebooks are linked under the Example column as Quick start, showcasing an easy to run example of the algorithm, or as Deep dive, explaining in detail the math and implementation of the algorithm. +The table below lists the recommendation algorithms currently available in the repository. Notebooks are linked under the Example column as Quick start, showcasing an easy to run example of the algorithm, or as Deep dive, explaining in detail the math and implementation of the algorithm. | Algorithm | Type | Description | Example | |-----------|------|-------------|---------| diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 9675bc7472..0000000000 --- a/docs/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Documentation - -To setup the documentation, first you need to install the dependencies of the full environment. For it please follow the [SETUP.md](../SETUP.md). Then type from the root folder of the repository: - - pip install -r docs/requirements-doc.txt - -To build the documentation: - - jupyter-book build docs - -To contribute to this repository, please follow our [coding guidelines](https://github.com/recommenders-team/recommenders/wiki/Coding-Guidelines). See also the [reStructuredText documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) for the syntax of docstrings. diff --git a/docs/_toc.yml b/docs/_toc.yml index 74d5c7101e..77e05f938a 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -3,7 +3,9 @@ format: jb-book root: intro -chapters: -- file: markdown -- file: notebooks -- file: markdown-notebooks +defaults: + numbered: false +parts: + - caption: Getting Started + chapters: + - file: ../SETUP.md \ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md index d06ab11e06..a551d7c9ec 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -23,5 +23,7 @@ The examples detail our learnings on five key tasks: Several utilities are provided in the `recommenders` library to support common tasks such as loading datasets in the format expected by different algorithms, evaluating model outputs, and splitting training/test data. Implementations of several state-of-the-art algorithms are included for self-study and customization in your own applications. + ```{tableofcontents} ``` + diff --git a/docs/markdown-notebooks.md b/docs/markdown-notebooks.md deleted file mode 100644 index a057a320dc..0000000000 --- a/docs/markdown-notebooks.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -jupytext: - formats: md:myst - text_representation: - extension: .md - format_name: myst - format_version: 0.13 - jupytext_version: 1.11.5 -kernelspec: - display_name: Python 3 - language: python - name: python3 ---- - -# Notebooks with MyST Markdown - -Jupyter Book also lets you write text-based notebooks using MyST Markdown. -See [the Notebooks with MyST Markdown documentation](https://jupyterbook.org/file-types/myst-notebooks.html) for more detailed instructions. -This page shows off a notebook written in MyST Markdown. - -## An example cell - -With MyST Markdown, you can define code cells with a directive like so: - -```{code-cell} -print(2 + 2) -``` - -When your book is built, the contents of any `{code-cell}` blocks will be -executed with your default Jupyter kernel, and their outputs will be displayed -in-line with the rest of your content. - -```{seealso} -Jupyter Book uses [Jupytext](https://jupytext.readthedocs.io/en/latest/) to convert text-based files to notebooks, and can support [many other text-based notebook files](https://jupyterbook.org/file-types/jupytext.html). -``` - -## Create a notebook with MyST Markdown - -MyST Markdown notebooks are defined by two things: - -1. YAML metadata that is needed to understand if / how it should convert text files to notebooks (including information about the kernel needed). - See the YAML at the top of this page for example. -2. The presence of `{code-cell}` directives, which will be executed with your book. - -That's all that is needed to get started! - -## Quickly add YAML metadata for MyST Notebooks - -If you have a markdown file and you'd like to quickly add YAML metadata to it, so that Jupyter Book will treat it as a MyST Markdown Notebook, run the following command: - -``` -jupyter-book myst init path/to/markdownfile.md -``` diff --git a/docs/markdown.md b/docs/markdown.md deleted file mode 100644 index 0ddaab3fb6..0000000000 --- a/docs/markdown.md +++ /dev/null @@ -1,55 +0,0 @@ -# Markdown Files - -Whether you write your book's content in Jupyter Notebooks (`.ipynb`) or -in regular markdown files (`.md`), you'll write in the same flavor of markdown -called **MyST Markdown**. -This is a simple file to help you get started and show off some syntax. - -## What is MyST? - -MyST stands for "Markedly Structured Text". It -is a slight variation on a flavor of markdown called "CommonMark" markdown, -with small syntax extensions to allow you to write **roles** and **directives** -in the Sphinx ecosystem. - -For more about MyST, see [the MyST Markdown Overview](https://jupyterbook.org/content/myst.html). - -## Sample Roles and Directives - -Roles and directives are two of the most powerful tools in Jupyter Book. They -are kind of like functions, but written in a markup language. They both -serve a similar purpose, but **roles are written in one line**, whereas -**directives span many lines**. They both accept different kinds of inputs, -and what they do with those inputs depends on the specific role or directive -that is being called. - -Here is a "note" directive: - -```{note} -Here is a note -``` - -It will be rendered in a special box when you build your book. - -Here is an inline directive to refer to a document: {doc}`markdown-notebooks`. - - -## Citations - -You can also cite references that are stored in a `bibtex` file. For example, -the following syntax: `` {cite}`holdgraf_evidence_2014` `` will render like -this: {cite}`holdgraf_evidence_2014`. - -Moreover, you can insert a bibliography into your page with this syntax: -The `{bibliography}` directive must be used for all the `{cite}` roles to -render properly. -For example, if the references for your book are stored in `references.bib`, -then the bibliography is inserted with: - -```{bibliography} -``` - -## Learn more - -This is just a simple starter to get you started. -You can learn a lot more at [jupyterbook.org](https://jupyterbook.org). diff --git a/docs/notebooks.ipynb b/docs/notebooks.ipynb deleted file mode 100644 index fdb7176c42..0000000000 --- a/docs/notebooks.ipynb +++ /dev/null @@ -1,122 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Content with notebooks\n", - "\n", - "You can also create content with Jupyter Notebooks. This means that you can include\n", - "code blocks and their outputs in your book.\n", - "\n", - "## Markdown + notebooks\n", - "\n", - "As it is markdown, you can embed images, HTML, etc into your posts!\n", - "\n", - "![](https://myst-parser.readthedocs.io/en/latest/_static/logo-wide.svg)\n", - "\n", - "You can also $add_{math}$ and\n", - "\n", - "$$\n", - "math^{blocks}\n", - "$$\n", - "\n", - "or\n", - "\n", - "$$\n", - "\\begin{aligned}\n", - "\\mbox{mean} la_{tex} \\\\ \\\\\n", - "math blocks\n", - "\\end{aligned}\n", - "$$\n", - "\n", - "But make sure you \\$Escape \\$your \\$dollar signs \\$you want to keep!\n", - "\n", - "## MyST markdown\n", - "\n", - "MyST markdown works in Jupyter Notebooks as well. For more information about MyST markdown, check\n", - "out [the MyST guide in Jupyter Book](https://jupyterbook.org/content/myst.html),\n", - "or see [the MyST markdown documentation](https://myst-parser.readthedocs.io/en/latest/).\n", - "\n", - "## Code blocks and outputs\n", - "\n", - "Jupyter Book will also embed your code blocks and output in your book.\n", - "For example, here's some sample Matplotlib code:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from matplotlib import rcParams, cycler\n", - "import matplotlib.pyplot as plt\n", - "import numpy as np\n", - "plt.ion()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "# Fixing random state for reproducibility\n", - "np.random.seed(19680801)\n", - "\n", - "N = 10\n", - "data = [np.logspace(0, 1, 100) + np.random.randn(100) + ii for ii in range(N)]\n", - "data = np.array(data).T\n", - "cmap = plt.cm.coolwarm\n", - "rcParams['axes.prop_cycle'] = cycler(color=cmap(np.linspace(0, 1, N)))\n", - "\n", - "\n", - "from matplotlib.lines import Line2D\n", - "custom_lines = [Line2D([0], [0], color=cmap(0.), lw=4),\n", - " Line2D([0], [0], color=cmap(.5), lw=4),\n", - " Line2D([0], [0], color=cmap(1.), lw=4)]\n", - "\n", - "fig, ax = plt.subplots(figsize=(10, 5))\n", - "lines = ax.plot(data)\n", - "ax.legend(custom_lines, ['Cold', 'Medium', 'Hot']);" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "There is a lot more that you can do with outputs (such as including interactive outputs)\n", - "with your book. For more information about this, see [the Jupyter Book documentation](https://jupyterbook.org)" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.8.0" - }, - "widgets": { - "application/vnd.jupyter.widget-state+json": { - "state": {}, - "version_major": 2, - "version_minor": 0 - } - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/docs/references.bib b/docs/references.bib deleted file mode 100644 index 783ec6aa5a..0000000000 --- a/docs/references.bib +++ /dev/null @@ -1,56 +0,0 @@ ---- ---- - -@inproceedings{holdgraf_evidence_2014, - address = {Brisbane, Australia, Australia}, - title = {Evidence for {Predictive} {Coding} in {Human} {Auditory} {Cortex}}, - booktitle = {International {Conference} on {Cognitive} {Neuroscience}}, - publisher = {Frontiers in Neuroscience}, - author = {Holdgraf, Christopher Ramsay and de Heer, Wendy and Pasley, Brian N. and Knight, Robert T.}, - year = {2014} -} - -@article{holdgraf_rapid_2016, - title = {Rapid tuning shifts in human auditory cortex enhance speech intelligibility}, - volume = {7}, - issn = {2041-1723}, - url = {http://www.nature.com/doifinder/10.1038/ncomms13654}, - doi = {10.1038/ncomms13654}, - number = {May}, - journal = {Nature Communications}, - author = {Holdgraf, Christopher Ramsay and de Heer, Wendy and Pasley, Brian N. and Rieger, Jochem W. and Crone, Nathan and Lin, Jack J. and Knight, Robert T. and Theunissen, Frédéric E.}, - year = {2016}, - pages = {13654}, - file = {Holdgraf et al. - 2016 - Rapid tuning shifts in human auditory cortex enhance speech intelligibility.pdf:C\:\\Users\\chold\\Zotero\\storage\\MDQP3JWE\\Holdgraf et al. - 2016 - Rapid tuning shifts in human auditory cortex enhance speech intelligibility.pdf:application/pdf} -} - -@inproceedings{holdgraf_portable_2017, - title = {Portable learning environments for hands-on computational instruction using container-and cloud-based technology to teach data science}, - volume = {Part F1287}, - isbn = {978-1-4503-5272-7}, - doi = {10.1145/3093338.3093370}, - abstract = {© 2017 ACM. There is an increasing interest in learning outside of the traditional classroom setting. This is especially true for topics covering computational tools and data science, as both are challenging to incorporate in the standard curriculum. These atypical learning environments offer new opportunities for teaching, particularly when it comes to combining conceptual knowledge with hands-on experience/expertise with methods and skills. Advances in cloud computing and containerized environments provide an attractive opportunity to improve the effciency and ease with which students can learn. This manuscript details recent advances towards using commonly-Available cloud computing services and advanced cyberinfrastructure support for improving the learning experience in bootcamp-style events. We cover the benets (and challenges) of using a server hosted remotely instead of relying on student laptops, discuss the technology that was used in order to make this possible, and give suggestions for how others could implement and improve upon this model for pedagogy and reproducibility.}, - booktitle = {{ACM} {International} {Conference} {Proceeding} {Series}}, - author = {Holdgraf, Christopher Ramsay and Culich, A. and Rokem, A. and Deniz, F. and Alegro, M. and Ushizima, D.}, - year = {2017}, - keywords = {Teaching, Bootcamps, Cloud computing, Data science, Docker, Pedagogy} -} - -@article{holdgraf_encoding_2017, - title = {Encoding and decoding models in cognitive electrophysiology}, - volume = {11}, - issn = {16625137}, - doi = {10.3389/fnsys.2017.00061}, - abstract = {© 2017 Holdgraf, Rieger, Micheli, Martin, Knight and Theunissen. Cognitive neuroscience has seen rapid growth in the size and complexity of data recorded from the human brain as well as in the computational tools available to analyze this data. This data explosion has resulted in an increased use of multivariate, model-based methods for asking neuroscience questions, allowing scientists to investigate multiple hypotheses with a single dataset, to use complex, time-varying stimuli, and to study the human brain under more naturalistic conditions. These tools come in the form of “Encoding” models, in which stimulus features are used to model brain activity, and “Decoding” models, in which neural features are used to generated a stimulus output. Here we review the current state of encoding and decoding models in cognitive electrophysiology and provide a practical guide toward conducting experiments and analyses in this emerging field. Our examples focus on using linear models in the study of human language and audition. We show how to calculate auditory receptive fields from natural sounds as well as how to decode neural recordings to predict speech. The paper aims to be a useful tutorial to these approaches, and a practical introduction to using machine learning and applied statistics to build models of neural activity. The data analytic approaches we discuss may also be applied to other sensory modalities, motor systems, and cognitive systems, and we cover some examples in these areas. In addition, a collection of Jupyter notebooks is publicly available as a complement to the material covered in this paper, providing code examples and tutorials for predictive modeling in python. The aimis to provide a practical understanding of predictivemodeling of human brain data and to propose best-practices in conducting these analyses.}, - journal = {Frontiers in Systems Neuroscience}, - author = {Holdgraf, Christopher Ramsay and Rieger, J.W. and Micheli, C. and Martin, S. and Knight, R.T. and Theunissen, F.E.}, - year = {2017}, - keywords = {Decoding models, Encoding models, Electrocorticography (ECoG), Electrophysiology/evoked potentials, Machine learning applied to neuroscience, Natural stimuli, Predictive modeling, Tutorials} -} - -@book{ruby, - title = {The Ruby Programming Language}, - author = {Flanagan, David and Matsumoto, Yukihiro}, - year = {2008}, - publisher = {O'Reilly Media} -} From 2b7a4c0dcf3559c37ecf910bd87ffd22702038e3 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Fri, 29 Dec 2023 09:56:47 +0100 Subject: [PATCH 05/49] Added rst files Signed-off-by: miguelgfierro --- docs/_config.yml | 6 +- docs/_toc.yml | 9 +- docs/datasets.rst | 152 +++++++++++++++++++++++++ docs/evaluation.rst | 16 +++ docs/index.rst | 26 +++++ docs/intro.md | 6 +- docs/models.rst | 264 ++++++++++++++++++++++++++++++++++++++++++++ docs/tuning.rst | 11 ++ docs/utils.rst | 70 ++++++++++++ 9 files changed, 554 insertions(+), 6 deletions(-) create mode 100644 docs/datasets.rst create mode 100644 docs/evaluation.rst create mode 100644 docs/index.rst create mode 100644 docs/models.rst create mode 100644 docs/tuning.rst create mode 100644 docs/utils.rst diff --git a/docs/_config.yml b/docs/_config.yml index 1853c84206..53ff793903 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -19,7 +19,7 @@ notebook_interface : "notebook" # Launch button settings repository: url : https://github.com/recommenders-team/recommenders - path_to_book : docs + path_to_book : /docs branch : main launch_buttons: @@ -42,4 +42,6 @@ sphinx: config: napoleon_google_docstring: True autodoc_member_order: groupwise - autoclass_content: both \ No newline at end of file + autoclass_content: both + + diff --git a/docs/_toc.yml b/docs/_toc.yml index 77e05f938a..3c34e3c7d7 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -8,4 +8,11 @@ defaults: parts: - caption: Getting Started chapters: - - file: ../SETUP.md \ No newline at end of file + - file: ../SETUP.md + - caption: Recommenders API Documentation + chapters: + - file: datasets + - file: evaluation + - file: models + - file: tuning + - file: utils diff --git a/docs/datasets.rst b/docs/datasets.rst new file mode 100644 index 0000000000..9cc88735ff --- /dev/null +++ b/docs/datasets.rst @@ -0,0 +1,152 @@ +.. _dataset: + +Dataset module +############## + +Recommendation datasets and related utilities + +Recommendation datasets +*********************** + +Amazon Reviews +============== + +`Amazon Reviews dataset `_ consists of reviews from Amazon. +The data span a period of 18 years, including ~35 million reviews up to March 2013. Reviews include product and user +information, ratings, and a plaintext review. + +:Citation: + + J. McAuley and J. Leskovec, "Hidden factors and hidden topics: understanding rating dimensions with review text", + RecSys, 2013. + +.. automodule:: recommenders.datasets.amazon_reviews + :members: + +CORD-19 +======= + +`COVID-19 Open Research Dataset (CORD-19) `_ is a full-text +and metadata dataset of COVID-19 and coronavirus-related scholarly articles optimized +for machine readability and made available for use by the global research community. + +In response to the COVID-19 pandemic, the Allen Institute for AI has partnered with leading research groups +to prepare and distribute the COVID-19 Open Research Dataset (CORD-19), a free resource of +over 47,000 scholarly articles, including over 36,000 with full text, about COVID-19 and the +coronavirus family of viruses for use by the global research community. + +This dataset is intended to mobilize researchers to apply recent advances in natural language processing +to generate new insights in support of the fight against this infectious disease. + +:Citation: + + Wang, L.L., Lo, K., Chandrasekhar, Y., Reas, R., Yang, J., Eide, D., + Funk, K., Kinney, R., Liu, Z., Merrill, W. and Mooney, P. "Cord-19: The COVID-19 Open Research Dataset.", 2020. + + +.. automodule:: recommenders.datasets.covid_utils + :members: + +Criteo +====== + +`Criteo dataset `_, released by Criteo Labs, is an online advertising dataset that contains feature values and click feedback +for millions of display Ads. Every Ad has has 40 attributes, the first attribute is the label where a value 1 represents +that the Ad has been clicked on and a 0 represents it wasn't clicked on. The rest consist of 13 integer columns and +26 categorical columns. + +.. automodule:: recommenders.datasets.criteo + :members: + +MIND +==== + +`MIcrosoft News Dataset (MIND) `_, is a large-scale dataset for news recommendation research. It was collected from +anonymized behavior logs of Microsoft News website. + +MIND contains about 160k English news articles and more than 15 million impression logs generated by 1 million users. +Every news article contains rich textual content including title, abstract, body, category and entities. +Each impression log contains the click events, non-clicked events and historical news click behaviors of this user before +this impression. To protect user privacy, each user was de-linked from the production system when securely hashed into an anonymized ID. + +:Citation: + + Fangzhao Wu, Ying Qiao, Jiun-Hung Chen, Chuhan Wu, Tao Qi, Jianxun Lian, Danyang Liu, Xing Xie, Jianfeng Gao, Winnie Wu + and Ming Zhou, "MIND: A Large-scale Dataset for News Recommendation", ACL, 2020. + + + +.. automodule:: recommenders.datasets.mind + :members: + +MovieLens +========= + +The `MovieLens datasets `_, first released in 1998, +describe people's expressed preferences +for movies. These preferences take the form of `` tuples, +each the result of a person expressing a preference (a 0-5 star rating) for a movie +at a particular time. + +It comes with several sizes: + +* MovieLens 100k: 100,000 ratings from 1000 users on 1700 movies. +* MovieLens 1M: 1 million ratings from 6000 users on 4000 movies. +* MovieLens 10M: 10 million ratings from 72000 users on 10000 movies. +* MovieLens 20M: 20 million ratings from 138000 users on 27000 movies + +:Citation: + + F. M. Harper and J. A. Konstan. "The MovieLens Datasets: History and Context". + ACM Transactions on Interactive Intelligent Systems (TiiS) 5, 4, Article 19, + DOI=http://dx.doi.org/10.1145/2827872, 2015. + +.. automodule:: recommenders.datasets.movielens + :members: + +Download utilities +****************** + +.. automodule:: recommenders.datasets.download_utils + :members: + + +Cosmos CLI utilities +********************* + +.. automodule:: recommenders.datasets.cosmos_cli + :members: + + +Pandas dataframe utilities +*************************** + +.. automodule:: recommenders.datasets.pandas_df_utils + :members: + + +Splitter utilities +****************** + +.. automodule:: recommenders.datasets.python_splitters + :members: + +.. automodule:: recommenders.datasets.spark_splitters + :members: + +.. automodule:: recommenders.datasets.split_utils + :members: + + +Sparse utilities +**************** + +.. automodule:: recommenders.datasets.sparse + :members: + + +Knowledge graph utilities +************************* + +.. automodule:: recommenders.datasets.wikidata + :members: diff --git a/docs/evaluation.rst b/docs/evaluation.rst new file mode 100644 index 0000000000..21fba4f7bf --- /dev/null +++ b/docs/evaluation.rst @@ -0,0 +1,16 @@ +.. _evaluation: + +Evaluation module +************************** + +Python evaluation +=============================== + +.. automodule:: recommenders.evaluation.python_evaluation + :members: + +PySpark evaluation +=============================== + +.. automodule:: recommenders.evaluation.spark_evaluation + :members: \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000..624d2cf63d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,26 @@ + +Recommender Utilities +=================================================== + +The `Recommenders repository `_ provides examples and best practices for building recommendation systems, provided as Jupyter notebooks. + +The module `recommenders `_ contains functions to simplify common tasks used when developing and +evaluating recommender systems. + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + Utils + Datasets + Evaluation + Recommender algorithms + Hyperparameter tuning + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/intro.md b/docs/intro.md index a551d7c9ec..4a36f520c7 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -19,11 +19,11 @@ The examples detail our learnings on five key tasks: - Model: Building models using various classical and deep learning recommendation algorithms such as Alternating Least Squares ([ALS](https://spark.apache.org/docs/latest/api/python/_modules/pyspark/ml/recommendation.html#ALS)) or eXtreme Deep Factorization Machines ([xDeepFM](https://arxiv.org/abs/1803.05170)). - Evaluate: Evaluating algorithms with offline metrics. - Model Select and Optimize: Tuning and optimizing hyperparameters for recommendation models. -- Operationalize: Operationalizing models in a production environment on Azure. +- Operationalize: Operationalizing models in a production environment. Several utilities are provided in the `recommenders` library to support common tasks such as loading datasets in the format expected by different algorithms, evaluating model outputs, and splitting training/test data. Implementations of several state-of-the-art algorithms are included for self-study and customization in your own applications. -```{tableofcontents} -``` + diff --git a/docs/models.rst b/docs/models.rst new file mode 100644 index 0000000000..4b5080869c --- /dev/null +++ b/docs/models.rst @@ -0,0 +1,264 @@ +.. _recommender: + +Recommender algorithms module +############################## + +Recommender system algorithms and utilities. + +Cornac +****************************** + +.. automodule:: recommenders.models.cornac.cornac_utils + :members: + +DeepRec +****************************** + +Base model +================== +.. automodule:: recommenders.models.deeprec.models.base_model + :members: + +DKN +================== +.. automodule:: recommenders.models.deeprec.models.dkn + :members: + +DKN item-to-item +================== +.. automodule:: recommenders.models.deeprec.models.dkn_item2item + :members: + +LightGCN +================== +.. automodule:: recommenders.models.deeprec.models.graphrec.lightgcn + :members: + +xDeepFM +============== +.. automodule:: recommenders.models.deeprec.models.xDeepFM + :members: + +Sequential models +================== + +Sequential base model +--------------------------- +.. automodule:: recommenders.models.deeprec.models.sequential.sequential_base_model + :members: + +A2SVD +------------- +.. automodule:: recommenders.models.deeprec.models.sequential.asvd + :members: + +Caser +---------------- +.. automodule:: recommenders.models.deeprec.models.sequential.caser + :members: + +GRU +-------------- +.. automodule:: recommenders.models.deeprec.models.sequential.gru + :members: + +NextItNet +-------------- +.. automodule:: recommenders.models.deeprec.models.sequential.nextitnet + :members: + +RNN Cells +------------ +.. automodule:: recommenders.models.deeprec.models.sequential.rnn_cell_implement + :members: + +SUM +------------------------- +.. automodule:: recommenders.models.deeprec.models.sequential.sum + :members: + +.. automodule:: recommenders.models.deeprec.models.sequential.sum_cells + :members: + +SLIRec +------------- +.. automodule:: recommenders.models.deeprec.models.sequential.sli_rec + :members: + +Iterators +=========== + +.. automodule:: recommenders.models.deeprec.io.iterator + :members: + +.. automodule:: recommenders.models.deeprec.io.dkn_iterator + :members: + +.. automodule:: recommenders.models.deeprec.io.dkn_item2item_iterator + :members: + +.. automodule:: recommenders.models.deeprec.io.nextitnet_iterator + :members: + +.. automodule:: recommenders.models.deeprec.io.sequential_iterator + :members: + +Data processing utilities +=========================== + +.. automodule:: recommenders.models.deeprec.DataModel.ImplicitCF + :members: + +Utilities +============ + +.. automodule:: recommenders.models.deeprec.deeprec_utils + :members: + +FastAI +****************************** + +.. automodule:: recommenders.models.fastai.fastai_utils + :members: + +GeoIMC +****************************** + +.. automodule:: recommenders.models.geoimc.geoimc_algorithm + :members: + +.. automodule:: recommenders.models.geoimc.geoimc_data + :members: + +.. automodule:: recommenders.models.geoimc.geoimc_predict + :members: + +.. automodule:: recommenders.models.geoimc.geoimc_utils + :members: + +LightFM +****************************** + +.. automodule:: recommenders.models.lightfm.lightfm_utils + :members: + +LightGBM +****************************** + +.. automodule:: recommenders.models.lightgbm.lightgbm_utils + :members: + +NCF +****************************** + +.. automodule:: recommenders.models.ncf.dataset + :members: + +.. automodule:: recommenders.models.ncf.ncf_singlenode + :members: + +NewsRec +****************************** + +.. automodule:: recommenders.models.newsrec.io.mind_all_iterator + :members: + +.. automodule:: recommenders.models.newsrec.io.mind_iterator + :members: + +.. automodule:: recommenders.models.newsrec.models.base_model + :members: + +.. automodule:: recommenders.models.newsrec.models.layers + :members: + +.. automodule:: recommenders.models.newsrec.models.lstur + :members: + +.. automodule:: recommenders.models.newsrec.models.naml + :members: + +.. automodule:: recommenders.models.newsrec.models.npa + :members: + +.. automodule:: recommenders.models.newsrec.models.nrms + :members: + +.. automodule:: recommenders.models.newsrec.newsrec_utils + :members: + +RBM +****************************** + +.. automodule:: recommenders.models.rbm.rbm + :members: + + +RLRMC +****************************** + +.. automodule:: recommenders.models.rlrmc.RLRMCalgorithm + :members: + +.. automodule:: recommenders.models.rlrmc.RLRMCdataset + :members: + +.. automodule:: recommenders.models.rlrmc.conjugate_gradient_ms + :members: + + +SAR +****************************** + +.. automodule:: recommenders.models.sar.sar_singlenode + :members: + +SASRec +****************************** + +.. automodule:: recommenders.models.sasrec.model + :members: + +.. automodule:: recommenders.models.sasrec.sampler + :members: + +.. automodule:: recommenders.models.sasrec.util + :members: + + +SSE-PT +****************************** + +.. automodule:: recommenders.models.sasrec.ssept + :members: + + +Surprise +****************************** + +.. automodule:: recommenders.models.surprise.surprise_utils + :members: + + +TF-IDF +****************************** + +.. automodule:: recommenders.models.tfidf.tfidf_utils + :members: + + +VAE +****************************** + +.. automodule:: recommenders.models.vae.multinomial_vae + :members: + +.. automodule:: recommenders.models.vae.standard_vae + :members: + + +Wide & Deep +****************************** + +.. automodule:: recommenders.models.wide_deep.wide_deep_utils + :members: \ No newline at end of file diff --git a/docs/tuning.rst b/docs/tuning.rst new file mode 100644 index 0000000000..24f0fab9bf --- /dev/null +++ b/docs/tuning.rst @@ -0,0 +1,11 @@ +.. _tuning: + +Hyperparameter tuning module +********************************* +Hyperparameter tuning module from Recommenders utilities. + +Parameter sweep utils +=============================== + +.. automodule:: recommenders.tuning.parameter_sweep + :members: \ No newline at end of file diff --git a/docs/utils.rst b/docs/utils.rst new file mode 100644 index 0000000000..b0f8b166e8 --- /dev/null +++ b/docs/utils.rst @@ -0,0 +1,70 @@ +.. _common: + +Common utilities module +************************** + + +General utilities +=============================== + +.. automodule:: recommenders.utils.general_utils + :members: + + +GPU utilities +=============================== + +.. automodule:: recommenders.utils.gpu_utils + :members: + + +Kubernetes utilities +=============================== + +.. automodule:: recommenders.utils.k8s_utils + :members: + + +Notebook utilities +=============================== + +.. automodule:: recommenders.utils.notebook_utils + :members: + +.. automodule:: recommenders.utils.notebook_memory_management + :members: + + +Python utilities +=============================== + +.. automodule:: recommenders.utils.python_utils + :members: + + +Spark utilities +=============================== + +.. automodule:: recommenders.utils.spark_utils + :members: + + +Tensorflow utilities +=============================== + +.. automodule:: recommenders.utils.tf_utils + :members: + + +Timer +=============================== + +.. automodule:: recommenders.utils.timer + :members: + + +Plot utilities +=============================== + +.. automodule:: recommenders.utils.plot + :members: \ No newline at end of file From 4dd227721df38c41ab8a6166d1c625cfbf21f80e Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Fri, 29 Dec 2023 10:15:36 +0100 Subject: [PATCH 06/49] license Signed-off-by: miguelgfierro --- docs/_config.yml | 8 ++++++++ docs/_toc.yml | 4 ++++ docs/intro.md | 5 +++++ 3 files changed, 17 insertions(+) diff --git a/docs/_config.yml b/docs/_config.yml index 53ff793903..b3b81366b8 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,6 +1,14 @@ +# Copyright (c) Recommenders contributors. +# Licensed under the MIT License. + # Book settings # Learn more at https://jupyterbook.org/customize/config.html +# To build the Jupyter Book: +# $ jupyter-book clean docs +# $ jupyter-book build docs + + title: Recommenders documentation author: Recommenders contributors logo: https://raw.githubusercontent.com/recommenders-team/artwork/main/color/recommenders_color.svg diff --git a/docs/_toc.yml b/docs/_toc.yml index 3c34e3c7d7..1ef2b5fc38 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -1,3 +1,6 @@ +# Copyright (c) Recommenders contributors. +# Licensed under the MIT License. + # Table of contents # Learn more at https://jupyterbook.org/customize/toc.html @@ -9,6 +12,7 @@ parts: - caption: Getting Started chapters: - file: ../SETUP.md + - file: TEMP - caption: Recommenders API Documentation chapters: - file: datasets diff --git a/docs/intro.md b/docs/intro.md index 4a36f520c7..cad0c74c27 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -1,3 +1,8 @@ + + # Welcome to Recommenders Recommenders objective is to assist researchers, developers and enthusiasts in prototyping, experimenting with and bringing to production a range of classic and state-of-the-art recommendation systems. From b45c3b05499ec535c17083a03f68224f484e6b3f Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Fri, 29 Dec 2023 19:56:32 +0100 Subject: [PATCH 07/49] Weird warning with a link in the docstrings Signed-off-by: miguelgfierro --- docs/datasets.rst | 7 ------ docs/index.rst | 26 --------------------- recommenders/evaluation/spark_evaluation.py | 11 ++++----- 3 files changed, 5 insertions(+), 39 deletions(-) delete mode 100644 docs/index.rst diff --git a/docs/datasets.rst b/docs/datasets.rst index 9cc88735ff..82352a5e95 100644 --- a/docs/datasets.rst +++ b/docs/datasets.rst @@ -111,13 +111,6 @@ Download utilities :members: -Cosmos CLI utilities -********************* - -.. automodule:: recommenders.datasets.cosmos_cli - :members: - - Pandas dataframe utilities *************************** diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 624d2cf63d..0000000000 --- a/docs/index.rst +++ /dev/null @@ -1,26 +0,0 @@ - -Recommender Utilities -=================================================== - -The `Recommenders repository `_ provides examples and best practices for building recommendation systems, provided as Jupyter notebooks. - -The module `recommenders `_ contains functions to simplify common tasks used when developing and -evaluating recommender systems. - -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - Utils - Datasets - Evaluation - Recommender algorithms - Hyperparameter tuning - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/recommenders/evaluation/spark_evaluation.py b/recommenders/evaluation/spark_evaluation.py index b4d6ea6891..f5e7cb47ef 100644 --- a/recommenders/evaluation/spark_evaluation.py +++ b/recommenders/evaluation/spark_evaluation.py @@ -187,7 +187,7 @@ def __init__( precision. The implementations of precision@k, ndcg@k, and mean average precision are referenced from Spark MLlib, which - can be found at `here `_. + can be found at `the link `_. Args: rating_true (pyspark.sql.DataFrame): DataFrame of true rating data (in the @@ -305,8 +305,8 @@ def precision_at_k(self): """Get precision@k. .. note:: - More details can be found - `here `_. + More details can be found + `on this website `_. Return: float: precision at k (min=0, max=1) @@ -330,7 +330,7 @@ def ndcg_at_k(self): .. note:: More details can be found - `here `_. + `on `_. Return: float: nDCG at k (min=0, max=1). @@ -349,8 +349,7 @@ def map_at_k(self): """Get mean average precision at k. .. note:: - More details can be found - `here `_. + More details `on this link `_. Return: float: MAP at k (min=0, max=1). From 7f32281c40c7eba9c4066c03fe7e6107cbb079fb Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sat, 30 Dec 2023 10:21:29 +0100 Subject: [PATCH 08/49] :memo: Signed-off-by: miguelgfierro --- recommenders/evaluation/spark_evaluation.py | 6 ++--- .../models/sequential/rnn_cell_implement.py | 24 +++++++++++++++++-- 2 files changed, 25 insertions(+), 5 deletions(-) diff --git a/recommenders/evaluation/spark_evaluation.py b/recommenders/evaluation/spark_evaluation.py index f5e7cb47ef..f0a0f4940a 100644 --- a/recommenders/evaluation/spark_evaluation.py +++ b/recommenders/evaluation/spark_evaluation.py @@ -203,7 +203,7 @@ def __init__( values are "top_k", "by_time_stamp", and "by_threshold". threshold (float): threshold for determining the relevant recommended items. This is used for the case that predicted ratings follow a known - distribution. NOTE: this option is only activated if relevancy_method is + distribution. NOTE: this option is only activated if `relevancy_method` is set to "by_threshold". """ self.rating_true = rating_true @@ -463,7 +463,7 @@ def _get_relevant_items_by_timestamp( col_rating (str): column name for rating. col_timestamp (str): column name for timestamp. col_prediction (str): column name for prediction. - k: number of relevent items to be filtered by the function. + k: number of relevant items to be filtered by the function. Return: pyspark.sql.DataFrame: DataFrame of customerID-itemID-rating tuples with only relevant items. @@ -525,7 +525,7 @@ def __init__( P. Castells, S. Vargas, and J. Wang, Novelty and diversity metrics for recommender systems: choice, discovery and relevance, ECIR 2011 - Eugene Yan, Serendipity: Accuracy’s unpopular best friend in Recommender Systems, + Eugene Yan, Serendipity: Accuracy's unpopular best friend in Recommender Systems, eugeneyan.com, April 2020 Args: diff --git a/recommenders/models/deeprec/models/sequential/rnn_cell_implement.py b/recommenders/models/deeprec/models/sequential/rnn_cell_implement.py index df7ea906fa..8d8f4c7827 100644 --- a/recommenders/models/deeprec/models/sequential/rnn_cell_implement.py +++ b/recommenders/models/deeprec/models/sequential/rnn_cell_implement.py @@ -59,7 +59,6 @@ def __init__( activation=None, reuse=None, ): - super(Time4LSTMCell, self).__init__(_reuse=reuse) if not state_is_tuple: logging.warn( @@ -127,6 +126,17 @@ def output_size(self): return self._output_size def call(self, inputs, state): + """Call method for the Time4LSTMCell. + + Args: + inputs: A 2D Tensor of shape [batch_size, input_size]. + state: A 2D Tensor of shape [batch_size, state_size]. + + Returns: + A tuple containing: + - A 2D Tensor of shape [batch_size, output_size]. + - A 2D Tensor of shape [batch_size, state_size]. + """ time_now_score = tf.expand_dims(inputs[:, -1], -1) time_last_score = tf.expand_dims(inputs[:, -2], -1) inputs = inputs[:, :-2] @@ -314,7 +324,6 @@ def __init__( activation=None, reuse=None, ): - super(Time4ALSTMCell, self).__init__(_reuse=reuse) if not state_is_tuple: logging.warn( @@ -382,6 +391,17 @@ def output_size(self): return self._output_size def call(self, inputs, state): + """Call method for the Time4ALSTMCell. + + Args: + inputs: A 2D Tensor of shape [batch_size, input_size]. + state: A 2D Tensor of shape [batch_size, state_size]. + + Returns: + A tuple containing: + - A 2D Tensor of shape [batch_size, output_size]. + - A 2D Tensor of shape [batch_size, state_size]. + """ att_score = tf.expand_dims(inputs[:, -1], -1) time_now_score = tf.expand_dims(inputs[:, -2], -1) time_last_score = tf.expand_dims(inputs[:, -3], -1) From 9e6f48feffb5d460591ecb3423346e518eaa8ead Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sat, 30 Dec 2023 10:49:56 +0100 Subject: [PATCH 09/49] Fix docstring errors and replace .. note:: with Note: Signed-off-by: miguelgfierro --- recommenders/datasets/pandas_df_utils.py | 2 +- recommenders/datasets/split_utils.py | 3 +-- recommenders/evaluation/spark_evaluation.py | 18 ++++++------- .../deeprec/models/sequential/nextitnet.py | 4 +-- recommenders/models/newsrec/models/layers.py | 26 +++++++++++++++---- recommenders/models/sar/sar_singlenode.py | 5 ++-- recommenders/utils/general_utils.py | 2 +- recommenders/utils/notebook_utils.py | 14 ++++------ recommenders/utils/python_utils.py | 2 +- recommenders/utils/tf_utils.py | 7 +++-- 10 files changed, 44 insertions(+), 39 deletions(-) diff --git a/recommenders/datasets/pandas_df_utils.py b/recommenders/datasets/pandas_df_utils.py index 74327392c4..50bd83dd8a 100644 --- a/recommenders/datasets/pandas_df_utils.py +++ b/recommenders/datasets/pandas_df_utils.py @@ -87,7 +87,7 @@ class LibffmConverter: """Converts an input dataframe to another dataframe in libffm format. A text file of the converted Dataframe is optionally generated. - .. note:: + Note: The input dataframe is expected to represent the feature data in the following schema: diff --git a/recommenders/datasets/split_utils.py b/recommenders/datasets/split_utils.py index 1ee6f4064b..da409292b3 100644 --- a/recommenders/datasets/split_utils.py +++ b/recommenders/datasets/split_utils.py @@ -138,8 +138,7 @@ def _get_column_name(name, col_user, col_item): def split_pandas_data_with_ratios(data, ratios, seed=42, shuffle=False): """Helper function to split pandas DataFrame with given ratios - .. note:: - + Note: Implementation referenced from `this source `_. Args: diff --git a/recommenders/evaluation/spark_evaluation.py b/recommenders/evaluation/spark_evaluation.py index f0a0f4940a..565ee9ce01 100644 --- a/recommenders/evaluation/spark_evaluation.py +++ b/recommenders/evaluation/spark_evaluation.py @@ -150,7 +150,7 @@ def rsquared(self): def exp_var(self): """Calculate explained variance. - .. note:: + Note: Spark MLLib's implementation is buggy (can lead to values > 1), hence we use var(). Returns: @@ -161,7 +161,7 @@ def exp_var(self): if var1 is None or var2 is None: return -np.inf - else: + else: # numpy divide is more tolerant to var2 being zero return 1 - np.divide(var1, var2) @@ -304,8 +304,8 @@ def _calculate_metrics(self): def precision_at_k(self): """Get precision@k. - .. note:: - More details can be found + Note: + More details can be found `on this website `_. Return: @@ -316,7 +316,7 @@ def precision_at_k(self): def recall_at_k(self): """Get recall@K. - .. note:: + Note: More details can be found `here `_. @@ -328,7 +328,7 @@ def recall_at_k(self): def ndcg_at_k(self): """Get Normalized Discounted Cumulative Gain (NDCG) - .. note:: + Note: More details can be found `on `_. @@ -348,7 +348,7 @@ def map(self): def map_at_k(self): """Get mean average precision at k. - .. note:: + Note: More details `on this link `_. Return: @@ -369,7 +369,7 @@ def _get_top_k_items( DataFrame, output a Spark DataFrame in the dense format of top k items for each user. - .. note:: + Note: if it is implicit rating, just append a column of constants to be ratings. Args: @@ -581,7 +581,6 @@ def __init__( ) ) if self.item_feature_df is not None: - if str(required_schema) != str(item_feature_df.schema): raise Exception( "Incorrect schema! item_feature_df should have schema " @@ -621,7 +620,6 @@ def _get_pairwise_items(self, df): ) def _get_cosine_similarity(self, n_partitions=200): - if self.item_sim_measure == "item_cooccurrence_count": # calculate item-item similarity based on item co-occurrence count self._get_cooccurrence_similarity(n_partitions) diff --git a/recommenders/models/deeprec/models/sequential/nextitnet.py b/recommenders/models/deeprec/models/sequential/nextitnet.py index ddf62b7ed0..3ba8a7912b 100644 --- a/recommenders/models/deeprec/models/sequential/nextitnet.py +++ b/recommenders/models/deeprec/models/sequential/nextitnet.py @@ -16,8 +16,7 @@ class NextItNetModel(SequentialBaseModel): Yuan, Fajie, et al. "A Simple Convolutional Generative Network for Next Item Recommendation", in Web Search and Data Mining, 2019. - .. note:: - + Note: It requires strong sequence with dataset. """ @@ -45,7 +44,6 @@ def _build_seq_graph(self): ) with tf.compat.v1.variable_scope("nextitnet", reuse=tf.compat.v1.AUTO_REUSE): - dilate_input = tf.concat( [item_history_embedding, cate_history_embedding], 2 ) diff --git a/recommenders/models/newsrec/models/layers.py b/recommenders/models/newsrec/models/layers.py index 669040cc5c..862996459c 100644 --- a/recommenders/models/newsrec/models/layers.py +++ b/recommenders/models/newsrec/models/layers.py @@ -56,7 +56,7 @@ def build(self, input_shape): super(AttLayer2, self).build(input_shape) # be sure you call this somewhere! def call(self, inputs, mask=None, **kwargs): - """Core implemention of soft attention + """Core implementation of soft attention. Args: inputs (object): input tensor. @@ -84,7 +84,7 @@ def call(self, inputs, mask=None, **kwargs): return K.sum(weighted_input, axis=1) def compute_mask(self, input, input_mask=None): - """Compte output mask value + """Compte output mask value. Args: input (object): input tensor. @@ -96,7 +96,7 @@ def compute_mask(self, input, input_mask=None): return None def compute_output_shape(self, input_shape): - """Compute shape of output tensor + """Compute shape of output tensor. Args: input_shape (tuple): shape of input tensor. @@ -112,7 +112,7 @@ class SelfAttention(layers.Layer): Args: multiheads (int): The number of heads. - head_dim (object): Dimention of each head. + head_dim (object): Dimension of each head. mask_right (boolean): whether to mask right words. Returns: @@ -313,6 +313,14 @@ def __init__(self, **kwargs): super(ComputeMasking, self).__init__(**kwargs) def call(self, inputs, **kwargs): + """Call method for ComputeMasking. + + Args: + inputs (object): input tensor. + + Returns: + bool tensor: True for values not equal to zero. + """ mask = K.not_equal(inputs, 0) return K.cast(mask, K.floatx()) @@ -321,7 +329,7 @@ def compute_output_shape(self, input_shape): class OverwriteMasking(layers.Layer): - """Set values at spasific positions to zero. + """Set values at specific positions to zero. Args: inputs (list): value tensor and mask tensor. @@ -337,6 +345,14 @@ def build(self, input_shape): super(OverwriteMasking, self).build(input_shape) def call(self, inputs, **kwargs): + """Call method for OverwriteMasking. + + Args: + inputs (list): value tensor and mask tensor. + + Returns: + object: tensor after setting values to zero. + """ return inputs[0] * K.expand_dims(inputs[1]) def compute_output_shape(self, input_shape): diff --git a/recommenders/models/sar/sar_singlenode.py b/recommenders/models/sar/sar_singlenode.py index 5cc2bc854b..570e0d04a3 100644 --- a/recommenders/models/sar/sar_singlenode.py +++ b/recommenders/models/sar/sar_singlenode.py @@ -226,9 +226,8 @@ def set_index(self, df): def fit(self, df): """Main fit method for SAR. - .. note:: - - Please make sure that `df` has no duplicates. + Note: + Please make sure that `df` has no duplicates. Args: df (pandas.DataFrame): User item rating dataframe (without duplicates). diff --git a/recommenders/utils/general_utils.py b/recommenders/utils/general_utils.py index 115e185328..92bc61b114 100644 --- a/recommenders/utils/general_utils.py +++ b/recommenders/utils/general_utils.py @@ -8,7 +8,7 @@ def invert_dictionary(dictionary): """Invert a dictionary - .. note:: + Note: If the dictionary has unique keys and unique values, the inversion would be perfect. However, if there are repeated values, the inversion can take different keys diff --git a/recommenders/utils/notebook_utils.py b/recommenders/utils/notebook_utils.py index 148b9ce2bf..e69d4632fa 100644 --- a/recommenders/utils/notebook_utils.py +++ b/recommenders/utils/notebook_utils.py @@ -57,10 +57,7 @@ def _update_parameters(parameter_cell_source, new_parameters): new_value = f'"{new_value}"' # Define a regular expression pattern to match parameter assignments and ignore comments - pattern = re.compile( - rf"(\b{param})\s*=\s*([^#\n]+)(?:#.*$)?", - re.MULTILINE - ) + pattern = re.compile(rf"(\b{param})\s*=\s*([^#\n]+)(?:#.*$)?", re.MULTILINE) modified_cell_source = pattern.sub(rf"\1 = {new_value}", modified_cell_source) return modified_cell_source @@ -71,11 +68,10 @@ def execute_notebook( ): """Execute a notebook while passing parameters to it. - .. note:: - - Ensure your Jupyter Notebook is set up with parameters that can be - modified and read. Use Markdown cells to specify parameters that need - modification and code cells to set parameters that need to be read. + Note: + Ensure your Jupyter Notebook is set up with parameters that can be + modified and read. Use Markdown cells to specify parameters that need + modification and code cells to set parameters that need to be read. Args: input_notebook (str): Path to the input notebook. diff --git a/recommenders/utils/python_utils.py b/recommenders/utils/python_utils.py index 44d802913b..6efdedfed4 100644 --- a/recommenders/utils/python_utils.py +++ b/recommenders/utils/python_utils.py @@ -234,7 +234,7 @@ def rescale(data, new_min=0, new_max=1, data_min=None, data_max=None): If data_min and data_max are explicitly provided, they will be used as the old min/max values instead of taken from the data. - .. note:: + Note: This is same as the `scipy.MinMaxScaler` with the exception that we can override the min/max of the old scale. diff --git a/recommenders/utils/tf_utils.py b/recommenders/utils/tf_utils.py index e50f659d0b..86b1cb6152 100644 --- a/recommenders/utils/tf_utils.py +++ b/recommenders/utils/tf_utils.py @@ -61,8 +61,7 @@ def pandas_input_fn( """Pandas input function for TensorFlow high-level API Estimator. This function returns a `tf.data.Dataset` function. - .. note:: - + Note: `tf.estimator.inputs.pandas_input_fn` cannot handle array/list column properly. For more information, see https://www.tensorflow.org/api_docs/python/tf/estimator/inputs/numpy_input_fn @@ -199,7 +198,7 @@ def evaluation_log_hook( ): """Evaluation log hook for TensorFlow high-level API Estimator. - .. note:: + Note: TensorFlow Estimator model uses the last checkpoint weights for evaluation or prediction. In order to get the most up-to-date evaluation results while training, set model's `save_checkpoints_steps` to be equal or greater than hook's `every_n_iter`. @@ -216,7 +215,7 @@ def evaluation_log_hook( batch_size (int): Number of samples fed into the model at a time. Note, the batch size doesn't affect on evaluation results. eval_fns (iterable of functions): List of evaluation functions that have signature of - (true_df, prediction_df, **eval_kwargs)->(float). If None, loss is calculated on true_df. + `(true_df, prediction_df, **eval_kwargs)`->`float`. If None, loss is calculated on `true_df`. eval_kwargs: Evaluation function's keyword arguments. Note, prediction column name should be 'prediction' From c5a0a1285e0389817086f3e87a674841a6c1d5b8 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sat, 30 Dec 2023 11:52:38 +0100 Subject: [PATCH 10/49] :memo: Signed-off-by: miguelgfierro --- docs/models.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/models.rst b/docs/models.rst index 4b5080869c..1b10901d32 100644 --- a/docs/models.rst +++ b/docs/models.rst @@ -29,16 +29,16 @@ DKN item-to-item .. automodule:: recommenders.models.deeprec.models.dkn_item2item :members: -LightGCN -================== -.. automodule:: recommenders.models.deeprec.models.graphrec.lightgcn - :members: - xDeepFM ============== .. automodule:: recommenders.models.deeprec.models.xDeepFM :members: +LightGCN +================== +.. automodule:: recommenders.models.deeprec.models.graphrec.lightgcn + :members: + Sequential models ================== @@ -257,6 +257,13 @@ VAE :members: +Vowpal Wabbit +****************************** + +.. automodule:: recommenders.models.vowpal_wabbit.vw + :members: + + Wide & Deep ****************************** From 0467655f594d2c8bdc029279388fbec64a2edad8 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sat, 30 Dec 2023 12:20:20 +0100 Subject: [PATCH 11/49] :memo: Signed-off-by: miguelgfierro --- docs/_toc.yml | 4 -- recommenders/evaluation/python_evaluation.py | 47 +++++++++++++++----- recommenders/evaluation/spark_evaluation.py | 8 ++-- 3 files changed, 39 insertions(+), 20 deletions(-) diff --git a/docs/_toc.yml b/docs/_toc.yml index 1ef2b5fc38..90e4fe0e17 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -9,10 +9,6 @@ root: intro defaults: numbered: false parts: - - caption: Getting Started - chapters: - - file: ../SETUP.md - - file: TEMP - caption: Recommenders API Documentation chapters: - file: datasets diff --git a/recommenders/evaluation/python_evaluation.py b/recommenders/evaluation/python_evaluation.py index 7569c7246c..e9adf621aa 100644 --- a/recommenders/evaluation/python_evaluation.py +++ b/recommenders/evaluation/python_evaluation.py @@ -33,10 +33,28 @@ class ColumnMismatchError(Exception): + """Exception raised when there is a mismatch in columns. + + This exception is raised when an operation involving columns + encounters a mismatch or inconsistency. + + Attributes: + message (str): Explanation of the error. + """ + pass class ColumnTypeMismatchError(Exception): + """Exception raised when there is a mismatch in column types. + + This exception is raised when an operation involving column types + encounters a mismatch or inconsistency. + + Attributes: + message (str): Explanation of the error. + """ + pass @@ -63,7 +81,7 @@ def check_column_dtypes_wrapper( col_item=DEFAULT_ITEM_COL, col_prediction=DEFAULT_PREDICTION_COL, *args, - **kwargs + **kwargs, ): """Check columns of DataFrame inputs @@ -81,12 +99,16 @@ def check_column_dtypes_wrapper( expected_true_columns.add(kwargs["col_rating"]) if not has_columns(rating_true, expected_true_columns): raise ColumnMismatchError("Missing columns in true rating DataFrame") - + if not has_columns(rating_pred, {col_user, col_item, col_prediction}): raise ColumnMismatchError("Missing columns in predicted rating DataFrame") - - if not has_same_base_dtype(rating_true, rating_pred, columns=[col_user, col_item]): - raise ColumnTypeMismatchError("Columns in provided DataFrames are not the same datatype") + + if not has_same_base_dtype( + rating_true, rating_pred, columns=[col_user, col_item] + ): + raise ColumnTypeMismatchError( + "Columns in provided DataFrames are not the same datatype" + ) return func( rating_true=rating_true, @@ -95,7 +117,7 @@ def check_column_dtypes_wrapper( col_item=col_item, col_prediction=col_prediction, *args, - **kwargs + **kwargs, ) return check_column_dtypes_wrapper @@ -750,7 +772,9 @@ def map_at_k( if df_merge is None: return 0.0 else: - return (df_merge["rr"] / df_merge["actual"].apply(lambda x: min(x, k))).sum() / n_users + return ( + df_merge["rr"] / df_merge["actual"].apply(lambda x: min(x, k)) + ).sum() / n_users def get_top_k_items( @@ -837,7 +861,7 @@ def check_column_dtypes_diversity_serendipity_wrapper( col_sim=DEFAULT_SIMILARITY_COL, col_relevance=None, *args, - **kwargs + **kwargs, ): """Check columns of DataFrame inputs @@ -904,7 +928,7 @@ def check_column_dtypes_diversity_serendipity_wrapper( col_sim=col_sim, col_relevance=col_relevance, *args, - **kwargs + **kwargs, ) return check_column_dtypes_diversity_serendipity_wrapper @@ -933,7 +957,7 @@ def check_column_dtypes_novelty_coverage_wrapper( col_user=DEFAULT_USER_COL, col_item=DEFAULT_ITEM_COL, *args, - **kwargs + **kwargs, ): """Check columns of DataFrame inputs @@ -969,7 +993,7 @@ def check_column_dtypes_novelty_coverage_wrapper( col_user=col_user, col_item=col_item, *args, - **kwargs + **kwargs, ) return check_column_dtypes_novelty_coverage_wrapper @@ -1006,7 +1030,6 @@ def _get_cosine_similarity( col_item=DEFAULT_ITEM_COL, col_sim=DEFAULT_SIMILARITY_COL, ): - if item_sim_measure == "item_cooccurrence_count": # calculate item-item similarity based on item co-occurrence count df_cosine_similarity = _get_cooccurrence_similarity( diff --git a/recommenders/evaluation/spark_evaluation.py b/recommenders/evaluation/spark_evaluation.py index 565ee9ce01..2e376edc28 100644 --- a/recommenders/evaluation/spark_evaluation.py +++ b/recommenders/evaluation/spark_evaluation.py @@ -306,7 +306,7 @@ def precision_at_k(self): Note: More details can be found - `on this website `_. + `on the precisionAt PySpark documentation `_. Return: float: precision at k (min=0, max=1) @@ -318,7 +318,7 @@ def recall_at_k(self): Note: More details can be found - `here `_. + `on the recallAt PySpark documentation `_. Return: float: recall at k (min=0, max=1). @@ -330,7 +330,7 @@ def ndcg_at_k(self): Note: More details can be found - `on `_. + `on the ndcgAt PySpark documentation `_. Return: float: nDCG at k (min=0, max=1). @@ -349,7 +349,7 @@ def map_at_k(self): """Get mean average precision at k. Note: - More details `on this link `_. + More details `on the meanAveragePrecision PySpark documentation `_. Return: float: MAP at k (min=0, max=1). From b887e439f743a5a02f7719cf7888434ea884a3e8 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sun, 31 Dec 2023 08:29:19 +0100 Subject: [PATCH 12/49] Automatic build of documentation Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 31 ++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 .github/workflows/update_documentation.yml diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml new file mode 100644 index 0000000000..758346b0e9 --- /dev/null +++ b/.github/workflows/update_documentation.yml @@ -0,0 +1,31 @@ +name: Update Documentation + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-22.04 + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: 3.8 + + - name: Install dependencies + run: | + pip install -r docs/requirements-doc.txt + + - name: Build and deploy documentation + run: | + jupyter-book build docs + cd docs + git add . + git commit -m "Update documentation" + git push origin gh-pages From 87225505814cbaba0de3e4d0b825268227817aa4 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sun, 31 Dec 2023 08:30:42 +0100 Subject: [PATCH 13/49] Automatic build of documentation dev Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 758346b0e9..b266fbc88c 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -3,7 +3,7 @@ name: Update Documentation on: push: branches: - - main + - miguel/jupyter_book jobs: build: From 20720f59c99d9967f83162368fa988d7e6fcc2a0 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sun, 31 Dec 2023 08:33:46 +0100 Subject: [PATCH 14/49] Automatic build of documentation deps Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index b266fbc88c..891da5a87a 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -20,6 +20,7 @@ jobs: - name: Install dependencies run: | + pip install . pip install -r docs/requirements-doc.txt - name: Build and deploy documentation From 23fa87c4d275e949f93cbc8cdccc60b9e8512154 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sun, 31 Dec 2023 08:46:57 +0100 Subject: [PATCH 15/49] Automatic build of documentation deps Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 891da5a87a..8d588e6dba 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -11,15 +11,16 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Set up Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v4 with: - python-version: 3.8 + python-version: 3.9 - name: Install dependencies run: | + pip install --no-use-pep517 lightfm pip install . pip install -r docs/requirements-doc.txt From 42cd1525b7a59fca9bf39b587354b43b38f6a4da Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sun, 31 Dec 2023 08:52:28 +0100 Subject: [PATCH 16/49] Automatic build of documentation deps Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 8d588e6dba..75d0718515 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -20,6 +20,7 @@ jobs: - name: Install dependencies run: | + pip install --upgrade pip setuptools wheel pip install --no-use-pep517 lightfm pip install . pip install -r docs/requirements-doc.txt From 9ac47442725e4232a7ead7fad37feb8fbdbb1c9b Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sun, 31 Dec 2023 08:56:40 +0100 Subject: [PATCH 17/49] Delete workflow and try via UI Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 34 ---------------------- 1 file changed, 34 deletions(-) delete mode 100644 .github/workflows/update_documentation.yml diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml deleted file mode 100644 index 75d0718515..0000000000 --- a/.github/workflows/update_documentation.yml +++ /dev/null @@ -1,34 +0,0 @@ -name: Update Documentation - -on: - push: - branches: - - miguel/jupyter_book - -jobs: - build: - runs-on: ubuntu-22.04 - - steps: - - name: Checkout repository - uses: actions/checkout@v3 - - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: 3.9 - - - name: Install dependencies - run: | - pip install --upgrade pip setuptools wheel - pip install --no-use-pep517 lightfm - pip install . - pip install -r docs/requirements-doc.txt - - - name: Build and deploy documentation - run: | - jupyter-book build docs - cd docs - git add . - git commit -m "Update documentation" - git push origin gh-pages From 020e497ae793236161ccea18da307ef2d6141e2d Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sun, 31 Dec 2023 09:28:52 +0100 Subject: [PATCH 18/49] Added again the workflow Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 37 ++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 .github/workflows/update_documentation.yml diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml new file mode 100644 index 0000000000..28fef98263 --- /dev/null +++ b/.github/workflows/update_documentation.yml @@ -0,0 +1,37 @@ +name: Update Documentation + +on: + push: + branches: + - miguel/jupyter_book + +jobs: + build: + runs-on: ubuntu-22.04 + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: 3.9 + + - name: Install dependencies + run: | + pip install --upgrade pip setuptools wheel + pip install --no-use-pep517 lightfm + pip install . + pip install -r docs/requirements-doc.txt + + - name: Build and deploy documentation + run: | + jupyter-book build docs + + - name: Build and deploy documentation + run: | + cd docs/_build/html + git add . + git commit -m "Update documentation" + git push origin gh-pages From 48b7cbcc712aa10cace36a96c98ffd55436cdd5d Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sun, 31 Dec 2023 09:34:00 +0100 Subject: [PATCH 19/49] git add * -rf Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 28fef98263..7bf050059b 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -32,6 +32,6 @@ jobs: - name: Build and deploy documentation run: | cd docs/_build/html - git add . + git add * -rf git commit -m "Update documentation" git push origin gh-pages From e5b9fb96c2e75059b393086708df17c7df0b0147 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sun, 31 Dec 2023 09:37:19 +0100 Subject: [PATCH 20/49] git add * -f Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 7bf050059b..2ccfb9cd84 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -32,6 +32,6 @@ jobs: - name: Build and deploy documentation run: | cd docs/_build/html - git add * -rf + git add * -f git commit -m "Update documentation" git push origin gh-pages From ea93f7bbd2036a26cc56d97d193828a484417810 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sun, 31 Dec 2023 17:19:36 +0100 Subject: [PATCH 21/49] add git info Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 2ccfb9cd84..e75c346275 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -32,6 +32,9 @@ jobs: - name: Build and deploy documentation run: | cd docs/_build/html + git config user.email "actions@github.com" + git config user.name "GitHub Actions" + git config user.signingkey "${{ secrets.GPG_KEY_ID }}" git add * -f git commit -m "Update documentation" git push origin gh-pages From 006a33d8c78b4e806d590fd1d366d60e73d194e2 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 18:47:40 +0100 Subject: [PATCH 22/49] actions to automatically update documentation Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index e75c346275..7182d3b180 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -25,11 +25,11 @@ jobs: pip install . pip install -r docs/requirements-doc.txt - - name: Build and deploy documentation + - name: Build documentation run: | jupyter-book build docs - - name: Build and deploy documentation + - name: Deploy documentation run: | cd docs/_build/html git config user.email "actions@github.com" From 9263c7d3914b3790eab182d5ac91a9181c84f825 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 18:56:42 +0100 Subject: [PATCH 23/49] actions to automatically update documentation Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 7182d3b180..08f61f8d9d 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -29,12 +29,24 @@ jobs: run: | jupyter-book build docs - - name: Deploy documentation + - name: Configure Git run: | - cd docs/_build/html - git config user.email "actions@github.com" - git config user.name "GitHub Actions" + git config --global user.email "actions@github.com" + git config --global user.name "GitHub Actions" git config user.signingkey "${{ secrets.GPG_KEY_ID }}" + + - name: Create and switch to gh-pages branch + run: | + git checkout gh-pages + git pull origin gh-pages || true + + - name: Copy built documentation + run: cp -r docs/_build/html/* . + + - name: Add and commit changes + run: | git add * -f git commit -m "Update documentation" - git push origin gh-pages + + - name: Push changes to gh-pages + run: git push origin gh-pages \ No newline at end of file From 5a221df288a6bf1d2a5bbe7655f3abd967f9365a Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 18:59:58 +0100 Subject: [PATCH 24/49] actions to automatically update documentation :bug: Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 08f61f8d9d..40806c22f0 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -37,7 +37,7 @@ jobs: - name: Create and switch to gh-pages branch run: | - git checkout gh-pages + git checkout -b gh-pages git pull origin gh-pages || true - name: Copy built documentation From b3217f813a0e0eb8d887ac38ba919757ae7966a4 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 19:14:03 +0100 Subject: [PATCH 25/49] actions to automatically update documentation :bug: Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 40806c22f0..e7e62d553e 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -43,10 +43,18 @@ jobs: - name: Copy built documentation run: cp -r docs/_build/html/* . - - name: Add and commit changes + # - name: Add and commit changes + # run: | + # git add * -f + # git commit -m "Update documentation" + + # - name: Push changes to gh-pages + # run: git push origin gh-pages + + - name: Deploy documentation run: | + git config user.email "actions@github.com" + git config user.name "GitHub Actions" git add * -f git commit -m "Update documentation" - - - name: Push changes to gh-pages - run: git push origin gh-pages \ No newline at end of file + git push origin HEAD:gh-pages \ No newline at end of file From 4809321fb72fb688589bf171bae138430df606af Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 19:21:30 +0100 Subject: [PATCH 26/49] trying github token Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index e7e62d553e..a0419ff030 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -57,4 +57,6 @@ jobs: git config user.name "GitHub Actions" git add * -f git commit -m "Update documentation" - git push origin HEAD:gh-pages \ No newline at end of file + git push origin HEAD:gh-pages + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file From 6d12b5b157f7165fb4f016d4f0ea884db55dfccd Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 19:39:20 +0100 Subject: [PATCH 27/49] trying github token Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 28 +++++++++++----------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index a0419ff030..47ec6b6dab 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -43,20 +43,20 @@ jobs: - name: Copy built documentation run: cp -r docs/_build/html/* . - # - name: Add and commit changes - # run: | - # git add * -f - # git commit -m "Update documentation" - - # - name: Push changes to gh-pages - # run: git push origin gh-pages - - - name: Deploy documentation + - name: Add and commit changes run: | - git config user.email "actions@github.com" - git config user.name "GitHub Actions" git add * -f git commit -m "Update documentation" - git push origin HEAD:gh-pages - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file + + - name: Push changes to gh-pages + run: git push origin gh-pages + + # - name: Deploy documentation + # run: | + # git config user.email "actions@github.com" + # git config user.name "GitHub Actions" + # git add * -f + # git commit -m "Update documentation" + # git push origin HEAD:gh-pages + # env: + # GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file From 5d75e4e9ebc3c2be099b41cddea3e83167283e18 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 20:08:37 +0100 Subject: [PATCH 28/49] trying github token and pull before pushing Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 47ec6b6dab..72dc97b814 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -33,7 +33,6 @@ jobs: run: | git config --global user.email "actions@github.com" git config --global user.name "GitHub Actions" - git config user.signingkey "${{ secrets.GPG_KEY_ID }}" - name: Create and switch to gh-pages branch run: | @@ -47,7 +46,10 @@ jobs: run: | git add * -f git commit -m "Update documentation" - + + - name: Pull latest changes from remote gh-pages branch + run: git pull origin gh-pages + - name: Push changes to gh-pages run: git push origin gh-pages From ee00e7ee91b9767390139e66528b1fe61f9f2e64 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 20:21:48 +0100 Subject: [PATCH 29/49] pull rebase Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 72dc97b814..210c54e7d4 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -47,6 +47,9 @@ jobs: git add * -f git commit -m "Update documentation" + - name: Configure pull strategy (rebase) + run: git config pull.rebase true + - name: Pull latest changes from remote gh-pages branch run: git pull origin gh-pages From 9af8f1a2994af1cadf760ea72651f3640d1c995a Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 20:28:42 +0100 Subject: [PATCH 30/49] pull rebase and -Xtheirs Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 210c54e7d4..26f53f5646 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -51,7 +51,7 @@ jobs: run: git config pull.rebase true - name: Pull latest changes from remote gh-pages branch - run: git pull origin gh-pages + run: git pull -Xtheirs origin gh-pages - name: Push changes to gh-pages run: git push origin gh-pages From 45919f21604f07d5dd73d63ff4cc0ea45cceab5d Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 20:42:30 +0100 Subject: [PATCH 31/49] clean Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 26f53f5646..239d3870ec 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -1,9 +1,14 @@ +# --------------------------------------------------------- +# Copyright (c) Recommenders contributors. +# Licensed under the MIT License. +# --------------------------------------------------------- + name: Update Documentation on: push: branches: - - miguel/jupyter_book + - main jobs: build: @@ -55,13 +60,3 @@ jobs: - name: Push changes to gh-pages run: git push origin gh-pages - - # - name: Deploy documentation - # run: | - # git config user.email "actions@github.com" - # git config user.name "GitHub Actions" - # git add * -f - # git commit -m "Update documentation" - # git push origin HEAD:gh-pages - # env: - # GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file From 769900801872e9f381aebeaff7ab6536f5c7614c Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 21:20:14 +0100 Subject: [PATCH 32/49] Update documentation badge Signed-off-by: miguelgfierro --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b67c1f1582..5e3ee3a62f 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Licensed under the MIT License. # Recommenders -[![Documentation Status](https://readthedocs.org/projects/microsoft-recommenders/badge/?version=latest)](https://microsoft-recommenders.readthedocs.io/en/latest/?badge=latest) +[![Documentation status](https://github.com/recommenders-team/recommenders/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/recommenders-team/recommenders/actions/workflows/pages/pages-build-deployment) From 4b2bba8866284b1c8ac5fd7df12e3f18b27ed421 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 21:26:10 +0100 Subject: [PATCH 33/49] install all deps Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 239d3870ec..a4d2142989 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -8,7 +8,7 @@ name: Update Documentation on: push: branches: - - main + - miguel/jupyter_book jobs: build: @@ -27,7 +27,7 @@ jobs: run: | pip install --upgrade pip setuptools wheel pip install --no-use-pep517 lightfm - pip install . + pip install .[all] pip install -r docs/requirements-doc.txt - name: Build documentation From 1abc9a62af64878b578622e4d6f72038fc837feb Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Thu, 4 Jan 2024 21:36:42 +0100 Subject: [PATCH 34/49] try adding other sphinx extensions Signed-off-by: miguelgfierro --- docs/_config.yml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index b3b81366b8..7fc06aa23b 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -45,8 +45,11 @@ sphinx: extra_extensions: - sphinx_inline_tabs - sphinx.ext.autodoc - - sphinx.ext.napoleon - - sphinx.ext.viewcode + - sphinx.ext.doctest + - sphinx.ext.intersphinx + - sphinx.ext.ifconfig + - sphinx.ext.napoleon # To render Google format docstrings + - sphinx.ext.viewcode # Add links to highlighted source code config: napoleon_google_docstring: True autodoc_member_order: groupwise From 5bea29bbe4bc6e65fc799a8c9476c2105a2e0db7 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Fri, 5 Jan 2024 08:46:38 +0100 Subject: [PATCH 35/49] Refact model rst Signed-off-by: miguelgfierro --- docs/models.rst | 190 ++++++++++++++++++++++++------------------------ 1 file changed, 96 insertions(+), 94 deletions(-) diff --git a/docs/models.rst b/docs/models.rst index 1b10901d32..92e7fa2b7b 100644 --- a/docs/models.rst +++ b/docs/models.rst @@ -5,267 +5,269 @@ Recommender algorithms module Recommender system algorithms and utilities. -Cornac +Cornac utilities ****************************** - .. automodule:: recommenders.models.cornac.cornac_utils :members: -DeepRec -****************************** +DeepRec utilities +****************************** Base model -================== +=========== .. automodule:: recommenders.models.deeprec.models.base_model :members: -DKN +Sequential base model ================== +.. automodule:: recommenders.models.deeprec.models.sequential.sequential_base_model + :members: + +Iterators +=========== +.. automodule:: recommenders.models.deeprec.io.iterator + :members: +.. automodule:: recommenders.models.deeprec.io.dkn_iterator + :members: +.. automodule:: recommenders.models.deeprec.io.dkn_item2item_iterator + :members: +.. automodule:: recommenders.models.deeprec.io.nextitnet_iterator + :members: +.. automodule:: recommenders.models.deeprec.io.sequential_iterator + :members: + +Data processing utilities +=========================== +.. automodule:: recommenders.models.deeprec.DataModel.ImplicitCF + :members: + +Utilities +============ +.. automodule:: recommenders.models.deeprec.deeprec_utils + :members: + + +DKN +****************************** .. automodule:: recommenders.models.deeprec.models.dkn :members: + DKN item-to-item -================== +****************************** .. automodule:: recommenders.models.deeprec.models.dkn_item2item :members: + xDeepFM -============== +****************************** .. automodule:: recommenders.models.deeprec.models.xDeepFM :members: + LightGCN -================== +****************************** .. automodule:: recommenders.models.deeprec.models.graphrec.lightgcn :members: -Sequential models -================== - -Sequential base model ---------------------------- -.. automodule:: recommenders.models.deeprec.models.sequential.sequential_base_model - :members: A2SVD -------------- +****************************** .. automodule:: recommenders.models.deeprec.models.sequential.asvd :members: + Caser ----------------- +****************************** .. automodule:: recommenders.models.deeprec.models.sequential.caser :members: + GRU --------------- +****************************** .. automodule:: recommenders.models.deeprec.models.sequential.gru :members: + NextItNet --------------- +****************************** .. automodule:: recommenders.models.deeprec.models.sequential.nextitnet :members: + RNN Cells ------------- +****************************** .. automodule:: recommenders.models.deeprec.models.sequential.rnn_cell_implement :members: + SUM -------------------------- +****************************** .. automodule:: recommenders.models.deeprec.models.sequential.sum :members: - .. automodule:: recommenders.models.deeprec.models.sequential.sum_cells :members: + SLIRec -------------- +****************************** .. automodule:: recommenders.models.deeprec.models.sequential.sli_rec :members: -Iterators -=========== - -.. automodule:: recommenders.models.deeprec.io.iterator - :members: -.. automodule:: recommenders.models.deeprec.io.dkn_iterator - :members: - -.. automodule:: recommenders.models.deeprec.io.dkn_item2item_iterator - :members: - -.. automodule:: recommenders.models.deeprec.io.nextitnet_iterator - :members: - -.. automodule:: recommenders.models.deeprec.io.sequential_iterator - :members: - -Data processing utilities -=========================== - -.. automodule:: recommenders.models.deeprec.DataModel.ImplicitCF - :members: - -Utilities -============ - -.. automodule:: recommenders.models.deeprec.deeprec_utils - :members: - -FastAI +FastAI utilities ****************************** - .. automodule:: recommenders.models.fastai.fastai_utils :members: + GeoIMC ****************************** - .. automodule:: recommenders.models.geoimc.geoimc_algorithm :members: - .. automodule:: recommenders.models.geoimc.geoimc_data :members: - .. automodule:: recommenders.models.geoimc.geoimc_predict :members: - .. automodule:: recommenders.models.geoimc.geoimc_utils :members: -LightFM -****************************** +LightFM utilities +****************************** .. automodule:: recommenders.models.lightfm.lightfm_utils :members: -LightGBM -****************************** +LightGBM utilities +****************************** .. automodule:: recommenders.models.lightgbm.lightgbm_utils :members: + NCF ****************************** - .. automodule:: recommenders.models.ncf.dataset :members: - .. automodule:: recommenders.models.ncf.ncf_singlenode :members: -NewsRec + +NewsRec utilities ****************************** +Base model +=========== +.. automodule:: recommenders.models.newsrec.models.base_model + :members: +Iterators +=========== .. automodule:: recommenders.models.newsrec.io.mind_all_iterator :members: - .. automodule:: recommenders.models.newsrec.io.mind_iterator :members: -.. automodule:: recommenders.models.newsrec.models.base_model - :members: - +Utilities +============ .. automodule:: recommenders.models.newsrec.models.layers :members: +.. automodule:: recommenders.models.newsrec.newsrec_utils + :members: + +LSTUR +****************************** .. automodule:: recommenders.models.newsrec.models.lstur :members: + +NAML +****************************** .. automodule:: recommenders.models.newsrec.models.naml :members: + +NPA +****************************** .. automodule:: recommenders.models.newsrec.models.npa :members: + +NRMS +****************************** .. automodule:: recommenders.models.newsrec.models.nrms :members: -.. automodule:: recommenders.models.newsrec.newsrec_utils - :members: RBM ****************************** - .. automodule:: recommenders.models.rbm.rbm :members: RLRMC ****************************** - -.. automodule:: recommenders.models.rlrmc.RLRMCalgorithm - :members: - .. automodule:: recommenders.models.rlrmc.RLRMCdataset :members: - +.. automodule:: recommenders.models.rlrmc.RLRMCalgorithm + :members: .. automodule:: recommenders.models.rlrmc.conjugate_gradient_ms :members: SAR ****************************** - .. automodule:: recommenders.models.sar.sar_singlenode :members: + SASRec ****************************** - .. automodule:: recommenders.models.sasrec.model :members: - .. automodule:: recommenders.models.sasrec.sampler :members: - .. automodule:: recommenders.models.sasrec.util :members: SSE-PT ****************************** - .. automodule:: recommenders.models.sasrec.ssept :members: -Surprise +Surprise utilities ****************************** - .. automodule:: recommenders.models.surprise.surprise_utils :members: -TF-IDF +TF-IDF utilities ****************************** - .. automodule:: recommenders.models.tfidf.tfidf_utils :members: -VAE +Standard VAE ****************************** - -.. automodule:: recommenders.models.vae.multinomial_vae - :members: - .. automodule:: recommenders.models.vae.standard_vae :members: -Vowpal Wabbit +Multinomial VAE ****************************** +.. automodule:: recommenders.models.vae.multinomial_vae + :members: + +Vowpal Wabbit utilities +****************************** .. automodule:: recommenders.models.vowpal_wabbit.vw :members: Wide & Deep ****************************** - .. automodule:: recommenders.models.wide_deep.wide_deep_utils :members: \ No newline at end of file From 072c6bd0e15ada90a662234b684a370f9a49a852 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Fri, 5 Jan 2024 08:53:39 +0100 Subject: [PATCH 36/49] comment geoimc and rlrmc docs until issue is fixed Signed-off-by: miguelgfierro --- docs/_config.yml | 5 +---- docs/models.rst | 43 ++++++++++++++++++++++--------------------- 2 files changed, 23 insertions(+), 25 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 7fc06aa23b..93e0040e9b 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -50,9 +50,6 @@ sphinx: - sphinx.ext.ifconfig - sphinx.ext.napoleon # To render Google format docstrings - sphinx.ext.viewcode # Add links to highlighted source code - config: - napoleon_google_docstring: True - autodoc_member_order: groupwise - autoclass_content: both + diff --git a/docs/models.rst b/docs/models.rst index 92e7fa2b7b..f90ccaa556 100644 --- a/docs/models.rst +++ b/docs/models.rst @@ -121,18 +121,6 @@ FastAI utilities :members: -GeoIMC -****************************** -.. automodule:: recommenders.models.geoimc.geoimc_algorithm - :members: -.. automodule:: recommenders.models.geoimc.geoimc_data - :members: -.. automodule:: recommenders.models.geoimc.geoimc_predict - :members: -.. automodule:: recommenders.models.geoimc.geoimc_utils - :members: - - LightFM utilities ****************************** .. automodule:: recommenders.models.lightfm.lightfm_utils @@ -204,15 +192,28 @@ RBM .. automodule:: recommenders.models.rbm.rbm :members: - -RLRMC -****************************** -.. automodule:: recommenders.models.rlrmc.RLRMCdataset - :members: -.. automodule:: recommenders.models.rlrmc.RLRMCalgorithm - :members: -.. automodule:: recommenders.models.rlrmc.conjugate_gradient_ms - :members: +.. FIXME: Fix Pymanopt dependency. Issue #2038 +.. GeoIMC +.. ****************************** +.. .. automodule:: recommenders.models.geoimc.geoimc_algorithm +.. :members: +.. .. automodule:: recommenders.models.geoimc.geoimc_data +.. :members: +.. .. automodule:: recommenders.models.geoimc.geoimc_predict +.. :members: +.. .. automodule:: recommenders.models.geoimc.geoimc_utils +.. :members: + + +.. FIXME: Fix Pymanopt dependency. Issue #2038 +.. RLRMC +.. ****************************** +.. .. automodule:: recommenders.models.rlrmc.RLRMCdataset +.. :members: +.. .. automodule:: recommenders.models.rlrmc.RLRMCalgorithm +.. :members: +.. .. automodule:: recommenders.models.rlrmc.conjugate_gradient_ms +.. :members: SAR From a8f0614adc16f7722ffe59d31f31134aa454d747 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Fri, 5 Jan 2024 08:55:41 +0100 Subject: [PATCH 37/49] :memo: Signed-off-by: miguelgfierro --- docs/models.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/models.rst b/docs/models.rst index f90ccaa556..ea36a956da 100644 --- a/docs/models.rst +++ b/docs/models.rst @@ -14,17 +14,17 @@ Cornac utilities DeepRec utilities ****************************** Base model -=========== +============================== .. automodule:: recommenders.models.deeprec.models.base_model :members: Sequential base model -================== +============================== .. automodule:: recommenders.models.deeprec.models.sequential.sequential_base_model :members: Iterators -=========== +============================== .. automodule:: recommenders.models.deeprec.io.iterator :members: .. automodule:: recommenders.models.deeprec.io.dkn_iterator @@ -37,12 +37,12 @@ Iterators :members: Data processing utilities -=========================== +============================== .. automodule:: recommenders.models.deeprec.DataModel.ImplicitCF :members: Utilities -============ +============================== .. automodule:: recommenders.models.deeprec.deeprec_utils :members: @@ -144,19 +144,19 @@ NCF NewsRec utilities ****************************** Base model -=========== +============================== .. automodule:: recommenders.models.newsrec.models.base_model :members: Iterators -=========== +============================== .. automodule:: recommenders.models.newsrec.io.mind_all_iterator :members: .. automodule:: recommenders.models.newsrec.io.mind_iterator :members: Utilities -============ +============================== .. automodule:: recommenders.models.newsrec.models.layers :members: .. automodule:: recommenders.models.newsrec.newsrec_utils From bb38687dd4858dcbc2db9f0b09e1456ae0c6006a Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Fri, 5 Jan 2024 09:27:18 +0100 Subject: [PATCH 38/49] Adding init and other special members Signed-off-by: miguelgfierro --- docs/models.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/models.rst b/docs/models.rst index ea36a956da..8416b91644 100644 --- a/docs/models.rst +++ b/docs/models.rst @@ -17,34 +17,43 @@ Base model ============================== .. automodule:: recommenders.models.deeprec.models.base_model :members: + :special-members: __init__ Sequential base model ============================== .. automodule:: recommenders.models.deeprec.models.sequential.sequential_base_model :members: + :special-members: __init__ Iterators ============================== .. automodule:: recommenders.models.deeprec.io.iterator :members: + :special-members: __init__ .. automodule:: recommenders.models.deeprec.io.dkn_iterator :members: + :special-members: __init__ .. automodule:: recommenders.models.deeprec.io.dkn_item2item_iterator :members: + :special-members: __init__ .. automodule:: recommenders.models.deeprec.io.nextitnet_iterator :members: + :special-members: __init__ .. automodule:: recommenders.models.deeprec.io.sequential_iterator :members: + :special-members: __init__ Data processing utilities ============================== .. automodule:: recommenders.models.deeprec.DataModel.ImplicitCF :members: + :special-members: __init__ Utilities ============================== .. automodule:: recommenders.models.deeprec.deeprec_utils :members: + :special-members: __init__, __repr__ DKN From 9952f1ceb92a877f95306c94ecc23ecd085ada70 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Fri, 5 Jan 2024 09:33:52 +0100 Subject: [PATCH 39/49] Adding init and other special members Signed-off-by: miguelgfierro --- docs/models.rst | 44 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/docs/models.rst b/docs/models.rst index 8416b91644..58712da51b 100644 --- a/docs/models.rst +++ b/docs/models.rst @@ -60,68 +60,80 @@ DKN ****************************** .. automodule:: recommenders.models.deeprec.models.dkn :members: + :special-members: __init__ DKN item-to-item ****************************** .. automodule:: recommenders.models.deeprec.models.dkn_item2item :members: + :special-members: __init__ xDeepFM ****************************** .. automodule:: recommenders.models.deeprec.models.xDeepFM :members: + :special-members: __init__ LightGCN ****************************** .. automodule:: recommenders.models.deeprec.models.graphrec.lightgcn :members: + :special-members: __init__ A2SVD ****************************** .. automodule:: recommenders.models.deeprec.models.sequential.asvd :members: + :special-members: __init__ Caser ****************************** .. automodule:: recommenders.models.deeprec.models.sequential.caser :members: + :special-members: __init__ GRU ****************************** .. automodule:: recommenders.models.deeprec.models.sequential.gru :members: + :special-members: __init__ NextItNet ****************************** .. automodule:: recommenders.models.deeprec.models.sequential.nextitnet :members: + :special-members: __init__ RNN Cells ****************************** .. automodule:: recommenders.models.deeprec.models.sequential.rnn_cell_implement :members: + :special-members: __init__ SUM ****************************** .. automodule:: recommenders.models.deeprec.models.sequential.sum :members: + :special-members: __init__ .. automodule:: recommenders.models.deeprec.models.sequential.sum_cells :members: + :special-members: __init__ SLIRec ****************************** .. automodule:: recommenders.models.deeprec.models.sequential.sli_rec :members: + :special-members: __init__ FastAI utilities @@ -146,8 +158,10 @@ NCF ****************************** .. automodule:: recommenders.models.ncf.dataset :members: + :special-members: __init__ .. automodule:: recommenders.models.ncf.ncf_singlenode :members: + :special-members: __init__ NewsRec utilities @@ -156,58 +170,71 @@ Base model ============================== .. automodule:: recommenders.models.newsrec.models.base_model :members: + :special-members: __init__ Iterators ============================== -.. automodule:: recommenders.models.newsrec.io.mind_all_iterator - :members: .. automodule:: recommenders.models.newsrec.io.mind_iterator :members: + :special-members: __init__ +.. automodule:: recommenders.models.newsrec.io.mind_all_iterator + :members: + :special-members: __init__ + Utilities ============================== .. automodule:: recommenders.models.newsrec.models.layers :members: + :special-members: __init__ .. automodule:: recommenders.models.newsrec.newsrec_utils :members: + :special-members: __init__ LSTUR ****************************** .. automodule:: recommenders.models.newsrec.models.lstur :members: + :special-members: __init__ NAML ****************************** .. automodule:: recommenders.models.newsrec.models.naml :members: + :special-members: __init__ NPA ****************************** .. automodule:: recommenders.models.newsrec.models.npa :members: + :special-members: __init__ NRMS ****************************** .. automodule:: recommenders.models.newsrec.models.nrms :members: + :special-members: __init__ RBM ****************************** .. automodule:: recommenders.models.rbm.rbm :members: + :special-members: __init__ .. FIXME: Fix Pymanopt dependency. Issue #2038 .. GeoIMC .. ****************************** .. .. automodule:: recommenders.models.geoimc.geoimc_algorithm .. :members: +.. :special-members: __init__ .. .. automodule:: recommenders.models.geoimc.geoimc_data .. :members: +.. :special-members: __init__ .. .. automodule:: recommenders.models.geoimc.geoimc_predict .. :members: .. .. automodule:: recommenders.models.geoimc.geoimc_utils @@ -219,24 +246,31 @@ RBM .. ****************************** .. .. automodule:: recommenders.models.rlrmc.RLRMCdataset .. :members: +.. :special-members: __init__ .. .. automodule:: recommenders.models.rlrmc.RLRMCalgorithm .. :members: +.. :special-members: __init__ .. .. automodule:: recommenders.models.rlrmc.conjugate_gradient_ms .. :members: +.. :special-members: __init__ + SAR ****************************** .. automodule:: recommenders.models.sar.sar_singlenode :members: + :special-members: __init__ SASRec ****************************** .. automodule:: recommenders.models.sasrec.model :members: + :special-members: __init__ .. automodule:: recommenders.models.sasrec.sampler :members: + :special-members: __init__ .. automodule:: recommenders.models.sasrec.util :members: @@ -245,6 +279,7 @@ SSE-PT ****************************** .. automodule:: recommenders.models.sasrec.ssept :members: + :special-members: __init__ Surprise utilities @@ -263,12 +298,14 @@ Standard VAE ****************************** .. automodule:: recommenders.models.vae.standard_vae :members: + :special-members: __init__ Multinomial VAE ****************************** .. automodule:: recommenders.models.vae.multinomial_vae :members: + :special-members: __init__ Vowpal Wabbit utilities @@ -280,4 +317,5 @@ Vowpal Wabbit utilities Wide & Deep ****************************** .. automodule:: recommenders.models.wide_deep.wide_deep_utils - :members: \ No newline at end of file + :members: + :special-members: __init__ \ No newline at end of file From ee608734f2d72ecfa4e4f9cf57eaf4ab901e29f0 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Fri, 5 Jan 2024 09:45:38 +0100 Subject: [PATCH 40/49] Reviewing other rst Signed-off-by: miguelgfierro --- docs/datasets.rst | 12 ++++++------ docs/evaluation.rst | 3 ++- docs/tuning.rst | 2 +- docs/utils.rst | 12 ++---------- 4 files changed, 11 insertions(+), 18 deletions(-) diff --git a/docs/datasets.rst b/docs/datasets.rst index 82352a5e95..448b965222 100644 --- a/docs/datasets.rst +++ b/docs/datasets.rst @@ -75,7 +75,6 @@ this impression. To protect user privacy, each user was de-linked from the produ and Ming Zhou, "MIND: A Large-scale Dataset for News Recommendation", ACL, 2020. - .. automodule:: recommenders.datasets.mind :members: @@ -106,40 +105,41 @@ It comes with several sizes: Download utilities ****************** - .. automodule:: recommenders.datasets.download_utils :members: Pandas dataframe utilities *************************** - .. automodule:: recommenders.datasets.pandas_df_utils :members: Splitter utilities ****************** - +Python splitters +================ .. automodule:: recommenders.datasets.python_splitters :members: +PySpark splitters +================= .. automodule:: recommenders.datasets.spark_splitters :members: +Other splitters utilities +========================= .. automodule:: recommenders.datasets.split_utils :members: Sparse utilities **************** - .. automodule:: recommenders.datasets.sparse :members: Knowledge graph utilities ************************* - .. automodule:: recommenders.datasets.wikidata :members: diff --git a/docs/evaluation.rst b/docs/evaluation.rst index 21fba4f7bf..1bd465c37f 100644 --- a/docs/evaluation.rst +++ b/docs/evaluation.rst @@ -13,4 +13,5 @@ PySpark evaluation =============================== .. automodule:: recommenders.evaluation.spark_evaluation - :members: \ No newline at end of file + :members: + :special-members: __init__ \ No newline at end of file diff --git a/docs/tuning.rst b/docs/tuning.rst index 24f0fab9bf..35f1dce1c5 100644 --- a/docs/tuning.rst +++ b/docs/tuning.rst @@ -4,8 +4,8 @@ Hyperparameter tuning module ********************************* Hyperparameter tuning module from Recommenders utilities. + Parameter sweep utils =============================== - .. automodule:: recommenders.tuning.parameter_sweep :members: \ No newline at end of file diff --git a/docs/utils.rst b/docs/utils.rst index b0f8b166e8..1e168a146a 100644 --- a/docs/utils.rst +++ b/docs/utils.rst @@ -6,65 +6,57 @@ Common utilities module General utilities =============================== - .. automodule:: recommenders.utils.general_utils :members: GPU utilities =============================== - .. automodule:: recommenders.utils.gpu_utils :members: Kubernetes utilities =============================== - .. automodule:: recommenders.utils.k8s_utils :members: Notebook utilities =============================== - .. automodule:: recommenders.utils.notebook_utils :members: - .. automodule:: recommenders.utils.notebook_memory_management :members: Python utilities =============================== - .. automodule:: recommenders.utils.python_utils :members: Spark utilities =============================== - .. automodule:: recommenders.utils.spark_utils :members: Tensorflow utilities =============================== - .. automodule:: recommenders.utils.tf_utils :members: + :special-members: __init__ Timer =============================== - .. automodule:: recommenders.utils.timer :members: + :special-members: __init__ Plot utilities =============================== - .. automodule:: recommenders.utils.plot :members: \ No newline at end of file From f892bf018bbc3f47bff738acaefa094ecdcbdf90 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Mon, 15 Jan 2024 17:34:20 +0100 Subject: [PATCH 41/49] Change sphinx version Signed-off-by: miguelgfierro --- docs/requirements-doc.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt index 2428eec0d3..1d2caf9435 100644 --- a/docs/requirements-doc.txt +++ b/docs/requirements-doc.txt @@ -1,4 +1,4 @@ jupyter-book -sphinx +sphinx>=5.1.0 sphinx_inline_tabs ghp-import \ No newline at end of file From e67715df90ee348766792f11634fe7aa718db583 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Mon, 15 Jan 2024 17:55:26 +0100 Subject: [PATCH 42/49] Change sphinx version and jupyter book Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 12 ++++++++---- docs/requirements-doc.txt | 4 ++-- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index a4d2142989..8bd2f9afbd 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -25,10 +25,14 @@ jobs: - name: Install dependencies run: | - pip install --upgrade pip setuptools wheel - pip install --no-use-pep517 lightfm - pip install .[all] - pip install -r docs/requirements-doc.txt + pip install -q --upgrade pip setuptools wheel + pip install -q --no-use-pep517 lightfm + pip install -q .[all] + pip install -q -r docs/requirements-doc.txt + + - name: List dependencies + run: | + pip list - name: Build documentation run: | diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt index 1d2caf9435..35d2833426 100644 --- a/docs/requirements-doc.txt +++ b/docs/requirements-doc.txt @@ -1,4 +1,4 @@ -jupyter-book -sphinx>=5.1.0 +jupyter-book>=0.13.2 +sphinx>=4.5.0 sphinx_inline_tabs ghp-import \ No newline at end of file From 32ee9d8a942a282fa9d3db95d8cee69d32a24556 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Mon, 15 Jan 2024 18:39:08 +0100 Subject: [PATCH 43/49] Change the way we compile the documentation Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 3 ++- docs/requirements-doc.txt | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index 8bd2f9afbd..d0cf90de87 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -36,7 +36,8 @@ jobs: - name: Build documentation run: | - jupyter-book build docs + jupyter-book config sphinx docs/ + sphinx-build docs docs/_build/html -b html - name: Configure Git run: | diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt index 35d2833426..c390c44c13 100644 --- a/docs/requirements-doc.txt +++ b/docs/requirements-doc.txt @@ -1,4 +1,4 @@ -jupyter-book>=0.13.2 -sphinx>=4.5.0 +jupyter-book>0.15.0 +sphinx>5.0.0 sphinx_inline_tabs ghp-import \ No newline at end of file From 6dcfdb12c92b00b0e88d05cb0cd87f366969ea1d Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sat, 27 Jan 2024 12:29:26 +0100 Subject: [PATCH 44/49] Using the latest JB release Signed-off-by: miguelgfierro --- docs/requirements-doc.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt index c390c44c13..7cab85feba 100644 --- a/docs/requirements-doc.txt +++ b/docs/requirements-doc.txt @@ -1,4 +1,4 @@ -jupyter-book>0.15.0 +jupyter-book>=1.0.0 sphinx>5.0.0 sphinx_inline_tabs ghp-import \ No newline at end of file From d090846697b7837914e10f353b5bc80dff3f5a0f Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Sat, 27 Jan 2024 12:39:21 +0100 Subject: [PATCH 45/49] Documentation working Signed-off-by: miguelgfierro --- .github/workflows/update_documentation.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/update_documentation.yml b/.github/workflows/update_documentation.yml index d0cf90de87..9779e5eed1 100644 --- a/.github/workflows/update_documentation.yml +++ b/.github/workflows/update_documentation.yml @@ -8,7 +8,7 @@ name: Update Documentation on: push: branches: - - miguel/jupyter_book + - main jobs: build: @@ -21,7 +21,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v4 with: - python-version: 3.9 + python-version: 3.10 - name: Install dependencies run: | From 126b9420029257d89fdc3fb1a8370dd607582306 Mon Sep 17 00:00:00 2001 From: Miguel Fierro <3491412+miguelgfierro@users.noreply.github.com> Date: Mon, 29 Jan 2024 16:59:32 +0100 Subject: [PATCH 46/49] Update docs/_config.yml Co-authored-by: Simon Zhao --- docs/_config.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/_config.yml b/docs/_config.yml index 93e0040e9b..027dc2da9a 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -43,7 +43,6 @@ html: sphinx: extra_extensions: - - sphinx_inline_tabs - sphinx.ext.autodoc - sphinx.ext.doctest - sphinx.ext.intersphinx From 76e56487ce699a0b4cc44cc35c807f04dca6afe2 Mon Sep 17 00:00:00 2001 From: Miguel Fierro <3491412+miguelgfierro@users.noreply.github.com> Date: Mon, 29 Jan 2024 16:59:46 +0100 Subject: [PATCH 47/49] Update docs/requirements-doc.txt Co-authored-by: Simon Zhao --- docs/requirements-doc.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt index 7cab85feba..fb57822187 100644 --- a/docs/requirements-doc.txt +++ b/docs/requirements-doc.txt @@ -1,4 +1,2 @@ jupyter-book>=1.0.0 -sphinx>5.0.0 -sphinx_inline_tabs ghp-import \ No newline at end of file From 972f09550bbcb88d4c8a5b517651335df155e8f1 Mon Sep 17 00:00:00 2001 From: Miguel Fierro <3491412+miguelgfierro@users.noreply.github.com> Date: Mon, 29 Jan 2024 16:59:58 +0100 Subject: [PATCH 48/49] Update docs/_config.yml Co-authored-by: Simon Zhao --- docs/_config.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/_config.yml b/docs/_config.yml index 027dc2da9a..efdd892209 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -11,6 +11,7 @@ title: Recommenders documentation author: Recommenders contributors +copyright: "2018-2024" logo: https://raw.githubusercontent.com/recommenders-team/artwork/main/color/recommenders_color.svg From 1aa1945d2d3190e053fb47c529fc58db7ebe3a65 Mon Sep 17 00:00:00 2001 From: miguelgfierro Date: Mon, 29 Jan 2024 17:02:24 +0100 Subject: [PATCH 49/49] Added comments by @SimonYansenZhao Signed-off-by: miguelgfierro --- .readthedocs.yaml | 20 -------------------- docs/requirements-doc.txt | 1 - 2 files changed, 21 deletions(-) delete mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml deleted file mode 100644 index c9b3305a62..0000000000 --- a/.readthedocs.yaml +++ /dev/null @@ -1,20 +0,0 @@ -version: 2 - -# Add necessary apt-get packages -build: - apt_packages: - - cmake - -# Explicitly set the version of Python and its requirements -# The flat extra_requirements all is equivalent to: pip install .[all] -python: - version: "3.7" - install: - - method: pip - path: . - extra_requirements: - - all - -# Build from the docs/ directory with Sphinx -sphinx: - configuration: docs/source/conf.py diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt index fb57822187..9810dc3c59 100644 --- a/docs/requirements-doc.txt +++ b/docs/requirements-doc.txt @@ -1,2 +1 @@ jupyter-book>=1.0.0 -ghp-import \ No newline at end of file