Template

Title of the notebooks should be concise and it's at heading-1 level, i.e., with one "#" in the markdown code.

Right under the notebook title, a brief introduction of the notebook is placed. Usually this will be what technical/business problems that the technical contents in this notebook try to solve.

Example:

This notebook shows how to set a version check for Recommenders.

0 Global settings

Heading-2 level is for each sections in the notebook. It starts from 0, where it is usually about global settings such as module imports, global variable definitions, etc. Name of the section starts with a capital letter.

Module imports

It is a good practice to add all the imports in the first cell.

python

import sys

import recommenders
from recommenders.utils.notebook_utils import store_metadata

print(f"System version: {sys.version}")
print(f"Recommenders version: {recommenders.__version__}")

Global variables

For the convenience of parameterizing notebook tests, tagging of "parameters" can be added to the cell such that variables in the cell can be found by papermill in testing.

python

RECOMMENDERS_VERSION = "0.1.1"

1 Section1

Each of the sections can be hierarchical. Level numbers are connect by ".".

1.1 Sub-section1

Note that

The Python codes in the notebook should follow PEP standard.
The code should be formatted with Black.

python

def check_version(version, current_version):
    v1_parts = version.split(".")
    v2_parts = current_version.split(".")

    # Pad the version parts with zeros to ensure equal length
    max_parts = max(len(v1_parts), len(v2_parts))
    v1_parts.extend(["0"] * (max_parts - len(v1_parts)))
    v2_parts.extend(["0"] * (max_parts - len(v2_parts)))

    for v1, v2 in zip(v1_parts, v2_parts):
        if int(v1) <= int(v2):
            print(f"{version} is older than {current_version}")
            return True
        elif int(v1) > int(v2):
            print(f"Error: {version} is newer than {current_version}")
            raise ValueError

python

checked_version = check_version(RECOMMENDERS_VERSION, recommenders.__version__)

Codes in a notebook are tested with store_metadata. Below the example shows how to record a variable for testing purpose.

python

store_metadata("checked_version", checked_version)

1.1.1 Sub-sub-section

1.2 Sub-section2

2 Section2

References

It is highly encouraged to have references for technical explanations in the notebooks for people to easily understand theories and reproduce codes.

Example:

Jianxu Lian et al, "xDeepFM: Combining Explicit and Implicit Feature Interactions for Recommender Systems", Proc. ACM KDD, London, UK, 2018, pp. 1754-1763.
PySpark MLlib evaluation metrics, url: https://spark.apache.org/docs/2.3.0/mllib-evaluation-metrics.html

Note this section, which is not the body sections of the notebook, does not have to be numbered in section name.