Add gallery of examples (#40)

Author: mirand863

README.md

@@ -191,9 +191,9 @@ predictions = pipeline.predict(X_test)
 
 ## Step-by-step walk-through
 
-A step-by-step walk-through is available on our interactive notebook hosted on [Google Colab](https://colab.research.google.com/drive/1Idzht9dNoB85pjc9gOL24t9ksrXZEA-9?usp=sharing).
+A step-by-step walk-through is available on our documentation hosted on [Read the Docs](https://hiclass.readthedocs.io/en/latest/index.html).
 
-This will guide you through the process of installing hiclass with conda, training and predicting a small dataset.
+This will guide you through the process of installing hiclass within a virtual environment, training, predicting, persisting models and much more.
 
 ## API documentation
 

docs/examples/README.rst

@@ -0,0 +1,4 @@
+Gallery of Examples
+===================
+
+These examples illustrate the main features of HiClass.

docs/source/algorithms/selecting_training_policy.rst renamed to docs/examples/plot_binary_policies.py

@@ -1,4 +1,7 @@
-Selecting a training policy
+# -*- coding: utf-8 -*-
+"""
+===========================
+Binary Training Policies
 ===========================
 
 The siblings policy is used by default on the local classifier per node, but the remaining ones can be selected with the parameter :literal:`binary_policy`, for example:
@@ -40,3 +43,36 @@
 
         rf = RandomForestClassifier()
         classifier = LocalClassifierPerNode(local_classifier=rf, binary_policy="exclusive_siblings")
+
+In the code below, the inclusive policy is selected.
+However, the code can be easily updated by replacing lines 20-21 with the examples shown in the tabs above.
+
+.. seealso::
+
+   Mathematical definition on the different policies is given at :ref:`Training Policies`.
+"""
+from sklearn.ensemble import RandomForestClassifier
+
+from hiclass import LocalClassifierPerNode
+
+# Define data
+X_train = [[1], [2], [3], [4]]
+X_test = [[4], [3], [2], [1]]
+Y_train = [
+    ["Animal", "Mammal", "Sheep"],
+    ["Animal", "Mammal", "Cow"],
+    ["Animal", "Reptile", "Snake"],
+    ["Animal", "Reptile", "Lizard"],
+]
+
+# Use random forest classifiers for every node
+# And exclusive siblings policy to select training examples for binary classifiers.
+rf = RandomForestClassifier()
+classifier = LocalClassifierPerNode(local_classifier=rf, binary_policy="inclusive")
+
+# Train local classifier per node
+classifier.fit(X_train, Y_train)
+
+# Predict
+predictions = classifier.predict(X_test)
+print(predictions)

docs/examples/plot_hello_hiclass.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+"""
+=====================
+Hello HiClass
+=====================
+
+A minimalist example showing how to use HiClass to train and predict.
+"""
+from sklearn.ensemble import RandomForestClassifier
+
+from hiclass import LocalClassifierPerNode
+
+# Define data
+X_train = [[1], [2], [3], [4]]
+X_test = [[4], [3], [2], [1]]
+Y_train = [
+    ["Animal", "Mammal", "Sheep"],
+    ["Animal", "Mammal", "Cow"],
+    ["Animal", "Reptile", "Snake"],
+    ["Animal", "Reptile", "Lizard"],
+]
+
+# Use random forest classifiers for every node
+rf = RandomForestClassifier()
+classifier = LocalClassifierPerNode(local_classifier=rf)
+
+# Train local classifier per node
+classifier.fit(X_train, Y_train)
+
+# Predict
+predictions = classifier.predict(X_test)
+print(predictions)

docs/examples/plot_model_persistence.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""
+=====================
+Model Persistence
+=====================
+
+HiClass is fully compatible with Pickle.
+Pickle can be used to easily store machine learning models on disk.
+In this example, we demonstrate how to use pickle to store and load trained classifiers.
+"""
+import pickle
+
+from sklearn.linear_model import LogisticRegression
+
+from hiclass import LocalClassifierPerLevel
+
+# Define data
+X_train = [[1, 2], [3, 4], [5, 6], [7, 8]]
+X_test = [[7, 8], [5, 6], [3, 4], [1, 2]]
+Y_train = [
+    ["Animal", "Mammal", "Sheep"],
+    ["Animal", "Mammal", "Cow"],
+    ["Animal", "Reptile", "Snake"],
+    ["Animal", "Reptile", "Lizard"],
+]
+
+# Use Logistic Regression classifiers for every level in the hierarchy
+lr = LogisticRegression()
+classifier = LocalClassifierPerLevel(local_classifier=lr)
+
+# Train local classifier per level
+classifier.fit(X_train, Y_train)
+
+# Save the model to disk
+filename = "trained_model.sav"
+pickle.dump(classifier, open(filename, "wb"))
+
+# Some time in the future...
+
+# Load the model from disk
+loaded_model = pickle.load(open(filename, "rb"))
+
+# Predict
+predictions = loaded_model.predict(X_test)
+print(predictions)

docs/examples/plot_parallel_training.py

@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*-
+"""
+=====================
+Parallel Training
+=====================
+
+Larger datasets require more time for training.
+While by default the models in HiClass are trained using a single core,
+it is possible to train each local classifier in parallel by leveraging the library Ray [1]_.
+In this example, we demonstrate how to train a hierarchical classifier in parallel,
+using all the cores available, on a mock dataset from Kaggle [2]_.
+
+.. [1] https://www.ray.io/
+.. [2] https://www.kaggle.com/datasets/kashnitsky/hierarchical-text-classification
+"""
+import sys
+from os import cpu_count
+
+import pandas as pd
+import requests
+from sklearn.feature_extraction.text import CountVectorizer, TfidfTransformer
+from sklearn.linear_model import LogisticRegression
+from sklearn.pipeline import Pipeline
+
+from hiclass import LocalClassifierPerParentNode
+
+
+def download(url: str, path: str) -> None:
+    """
+    Download a file from the internet.
+
+    Parameters
+    ----------
+    url : str
+        The address of the file to be downloaded.
+    path : str
+        The path to store the downloaded file.
+    """
+    response = requests.get(url)
+    with open(path, "wb") as file:
+        file.write(response.content)
+
+
+# Download training data
+training_data_url = "https://zenodo.org/record/6657410/files/train_40k.csv?download=1"
+training_data_path = "train_40k.csv"
+download(training_data_url, training_data_path)
+
+# Load training data into pandas dataframe
+training_data = pd.read_csv(training_data_path).fillna(" ")
+
+# We will use logistic regression classifiers for every parent node
+lr = LogisticRegression(max_iter=1000)
+
+pipeline = Pipeline(
+    [
+        ("count", CountVectorizer()),
+        ("tfidf", TfidfTransformer()),
+        (
+            "lcppn",
+            LocalClassifierPerParentNode(local_classifier=lr, n_jobs=cpu_count()),
+        ),
+    ]
+)
+
+# Select training data
+X_train = training_data["Title"]
+Y_train = training_data[["Cat1", "Cat2", "Cat3"]]
+
+# Fixes bug AttributeError: '_LoggingTee' object has no attribute 'fileno'
+# This only happens when building the documentation
+# Hence, you don't actually need it for your code to work
+sys.stdout.fileno = lambda: False
+
+# Now, let's train the local classifier per parent node
+pipeline.fit(X_train, Y_train)

docs/examples/plot_pipeline.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""
+=====================
+Building Pipelines
+=====================
+
+HiClass can be adopted in scikit-learn pipelines, and fully supports sparse matrices as input.
+This example desmonstrates the use of both of these features.
+"""
+from sklearn.feature_extraction.text import CountVectorizer, TfidfTransformer
+from sklearn.linear_model import LogisticRegression
+from sklearn.pipeline import Pipeline
+
+from hiclass import LocalClassifierPerParentNode
+
+# Define data
+X_train = [
+    "Struggling to repay loan",
+    "Unable to get annual report",
+]
+X_test = [
+    "Unable to get annual report",
+    "Struggling to repay loan",
+]
+Y_train = [["Loan", "Student loan"], ["Credit reporting", "Reports"]]
+
+# We will use logistic regression classifiers for every parent node
+lr = LogisticRegression()
+
+# Let's build a pipeline using CountVectorizer and TfidfTransformer
+# to extract features as sparse matrices
+pipeline = Pipeline(
+    [
+        ("count", CountVectorizer()),
+        ("tfidf", TfidfTransformer()),
+        ("lcppn", LocalClassifierPerParentNode(local_classifier=lr)),
+    ]
+)
+
+# Now, let's train a local classifier per parent node
+pipeline.fit(X_train, Y_train)
+
+# Finally, let's predict using the pipeline
+predictions = pipeline.predict(X_test)
+print(predictions)

docs/requirements.txt

@@ -2,4 +2,7 @@
 sphinx==5.0.0
 sphinx_rtd_theme==1.0.0
 readthedocs-sphinx-search==0.1.2
-sphinx_code_tabs==0.5.3
+sphinx_code_tabs==0.5.3
+sphinx-gallery==0.10.1
+matplotlib==3.5.2
+pandas==1.4.2

docs/source/algorithms/local_classifier_per_node.rst

@@ -14,6 +14,5 @@ One of the most popular approaches in the literature, the local classifier per n
     :hidden:
 
     training_policies
-    selecting_training_policy
 
 Each binary classifier is trained in parallel using the library `Ray <https://www.ray.io/>`_. In order to avoid inconsistencies, prediction is performed in a top-down manner. For example, given a hypothetical test example, the local classifier per node firstly queries the binary classifiers at nodes "Reptile" and "Mammal". Let's suppose that in this case the probability of the test example belonging to class "Reptile" is 0.8, while the probability of belonging to class "Mammal" is 0.5, then class "Reptile" is picked. At the next level, only the classifiers at nodes "Snake" and "Lizard" are queried, and again the one with the highest probability is selected.

docs/source/algorithms/metrics.rst

@@ -1,6 +1,6 @@
 .. _metrics-overview:
 
-Hierarchical Metrics
+Metrics
 ====================
 
 According to [1]_, the use of flat classification metrics might not be adequate to give enough insight of which algorithm is better at classifying hierarchical data. Hence, in HiClass we implemented the metrics of hierarchical precision (hP), hierarchical recall (hR) and hierarchical F-score (hF), which are extensions of the renowned metrics of precision, recall and F-score, but tailored to the hierarchical classification scenario. These hierarchical counterparts were initially proposed by [2]_, and are defined as follows: