Add binary policies to documentation (#55)

* Add binary policies to documentation

* Increase test coverage

* Fix if else for ray verification

* Specify version of dependencies for tests

Author: mirand863

.github/workflows/deploy-pypi.yml

@@ -23,10 +23,11 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install pytest
-        python -m pip install pytest-flake8
-        python -m pip install pytest-pydocstyle
-        python -m pip install pytest-cov
+        python -m pip install flake8==4.0.1
+        python -m pip install pytest==7.1.2
+        python -m pip install pytest-flake8==1.1.1
+        python -m pip install pytest-pydocstyle==2.3.0
+        python -m pip install pytest-cov==3.0.0
         python -m pip install .
     - name: Test with pytest
       run: |

.github/workflows/test-pr.yml

@@ -24,10 +24,11 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install pytest
-        python -m pip install pytest-flake8
-        python -m pip install pytest-pydocstyle
-        python -m pip install pytest-cov
+        python -m pip install flake8==4.0.1
+        python -m pip install pytest==7.1.2
+        python -m pip install pytest-flake8==1.1.1
+        python -m pip install pytest-pydocstyle==2.3.0
+        python -m pip install pytest-cov==3.0.0
         python -m pip install .
     - name: Test with pytest
       run: |

CONTRIBUTING.md

@@ -10,13 +10,14 @@ Please make sure all tests pass before submitting a pull request. It is also goo
 
 ## Testing the code locally
 
-To test the code locally you need to install the dependencies for the library in the current environment. Additionally, you need to install the following dependencies for testing:
+To test the code locally you need to install the dependencies for the library in the current environment. Additionally, you need to install the dependencies for testing. All of those dependencies can be installed with:
 
 ```
-pip install pytest
-pip install pytest-flake8
-pip install pytest-pydocstyle
-pip install pytest-cov
+pip install flake8==4.0.1
+pip install pytest==7.1.2
+pip install pytest-flake8==1.1.1
+pip install pytest-pydocstyle==2.3.0
+pip install pytest-cov==3.0.0
 pip install -e .
 ```
 

docs/examples/plot_parallel_training.py

@@ -7,6 +7,7 @@
 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]_.
+If Ray is not installed, the parallelism defaults to Joblib.
 In this example, we demonstrate how to train a hierarchical classifier in parallel by
 setting the parameter :literal:`n_jobs` to use all the cores available. Training
 is performed on a mock dataset from Kaggle [2]_.

hiclass/HierarchicalClassifier.py

@@ -4,16 +4,16 @@
 
 import networkx as nx
 import numpy as np
+from joblib import Parallel, delayed
+from sklearn.base import BaseEstimator
+from sklearn.linear_model import LogisticRegression
 
 try:
     import ray
 except ImportError:
     _has_ray = False
-    from joblib import Parallel, delayed, effective_n_jobs
 else:
     _has_ray = True
-from sklearn.base import BaseEstimator
-from sklearn.linear_model import LogisticRegression
 
 
 def make_leveled(y):
@@ -85,6 +85,7 @@ def __init__(
             a single unique class.
         n_jobs : int, default=1
             The number of jobs to run in parallel. Only :code:`fit` is parallelized.
+            If :code:`Ray` is installed it is used, otherwise it defaults to :code:`Joblib`.
         classifier_abbreviation : str, default=""
             The abbreviation of the local hierarchical classifier to be displayed during logging.
         """
@@ -296,9 +297,11 @@ def _remove_separator(self, y):
                 for j in range(1, y.shape[1]):
                     y[i, j] = y[i, j].split(self.separator_)[-1]
 
-    def _fit_node_classifier(self, nodes, local_mode):
+    def _fit_node_classifier(
+        self, nodes, local_mode: bool = False, use_joblib: bool = False
+    ):
         if self.n_jobs > 1:
-            if _has_ray:
+            if _has_ray and not use_joblib:
                 ray.init(
                     num_cpus=self.n_jobs,
                     local_mode=local_mode,

hiclass/LocalClassifierPerLevel.py

@@ -6,19 +6,19 @@
 from copy import deepcopy
 
 import numpy as np
+from joblib import Parallel, delayed
+from sklearn.base import BaseEstimator
+from sklearn.utils.validation import check_array, check_is_fitted
+
+from hiclass.ConstantClassifier import ConstantClassifier
+from hiclass.HierarchicalClassifier import HierarchicalClassifier
 
 try:
     import ray
 except ImportError:
     _has_ray = False
-    from joblib import Parallel, delayed, effective_n_jobs
 else:
     _has_ray = True
-from sklearn.base import BaseEstimator
-from sklearn.utils.validation import check_array, check_is_fitted
-
-from hiclass.ConstantClassifier import ConstantClassifier
-from hiclass.HierarchicalClassifier import HierarchicalClassifier
 
 
 class LocalClassifierPerLevel(BaseEstimator, HierarchicalClassifier):
@@ -67,6 +67,7 @@ def __init__(
             a single unique class.
         n_jobs : int, default=1
             The number of jobs to run in parallel. Only :code:`fit` is parallelized.
+            If :code:`Ray` is installed it is used, otherwise it defaults to :code:`Joblib`.
         """
         super().__init__(
             local_classifier=local_classifier,
@@ -198,10 +199,10 @@ def _initialize_local_classifiers(self):
         ]
         self.masks_ = [None for _ in range(self.y_.shape[1])]
 
-    def _fit_digraph(self, local_mode: bool = False):
+    def _fit_digraph(self, local_mode: bool = False, use_joblib: bool = False):
         self.logger_.info("Fitting local classifiers")
         if self.n_jobs > 1:
-            if _has_ray:
+            if _has_ray and not use_joblib:
                 ray.init(
                     num_cpus=self.n_jobs,
                     local_mode=local_mode,

hiclass/LocalClassifierPerNode.py

@@ -51,8 +51,17 @@ def __init__(
         local_classifier : BaseEstimator, default=LogisticRegression
             The local_classifier used to create the collection of local classifiers. Needs to have fit, predict and
             clone methods.
-        binary_policy : str, default="siblings"
-            Rules for defining positive and negative training examples.
+        binary_policy : {"exclusive", "less_exclusive", "exclusive_siblings", "inclusive", "less_inclusive", "siblings"}, str, default="siblings"
+            Specify the rule for defining positive and negative training examples, using one of the following options:
+
+            - `exclusive`: Positive examples belong only to the class being considered. All classes are negative examples, except for the selected class;
+            - `less_exclusive`: Positive examples belong only to the class being considered. All classes are negative examples, except for the selected class and its descendants;
+            - `exclusive_siblings`: Positive examples belong only to the class being considered. All sibling classes are negative examples;
+            - `inclusive`: Positive examples belong only to the class being considered and its descendants. All classes are negative examples, except for the selected class, its descendants and ancestors;
+            - `less_inclusive`: Positive examples belong only to the class being considered and its descendants. All classes are negative examples, except for the selected class and its descendants;
+            - `siblings`: Positive examples belong only to the class being considered and its descendants. All siblings and their descendant classes are negative examples.
+
+            See :ref:`Training Policies` for more information about the different policies.
         verbose : int, default=0
             Controls the verbosity when fitting and predicting.
             See https://verboselogs.readthedocs.io/en/latest/readme.html#overview-of-logging-levels
@@ -64,6 +73,7 @@ def __init__(
             a single unique class.
         n_jobs : int, default=1
             The number of jobs to run in parallel. Only :code:`fit` is parallelized.
+            If :code:`Ray` is installed it is used, otherwise it defaults to :code:`Joblib`.
         """
         super().__init__(
             local_classifier=local_classifier,
@@ -206,12 +216,12 @@ def _initialize_local_classifiers(self):
                 }
         nx.set_node_attributes(self.hierarchy_, local_classifiers)
 
-    def _fit_digraph(self, local_mode: bool = False):
+    def _fit_digraph(self, local_mode: bool = False, use_joblib: bool = False):
         self.logger_.info("Fitting local classifiers")
         nodes = list(self.hierarchy_.nodes)
         # Remove root because it does not need to be fitted
         nodes.remove(self.root_)
-        self._fit_node_classifier(nodes, local_mode)
+        self._fit_node_classifier(nodes, local_mode, use_joblib)
 
     @staticmethod
     def _fit_classifier(self, node):

hiclass/LocalClassifierPerParentNode.py

@@ -60,6 +60,7 @@ def __init__(
             a single unique class.
         n_jobs : int, default=1
             The number of jobs to run in parallel. Only :code:`fit` is parallelized.
+            If :code:`Ray` is installed it is used, otherwise it defaults to :code:`Joblib`.
         """
         super().__init__(
             local_classifier=local_classifier,
@@ -199,7 +200,7 @@ def _fit_classifier(self, node):
         classifier.fit(X, y)
         return classifier
 
-    def _fit_digraph(self, local_mode: bool = False):
+    def _fit_digraph(self, local_mode: bool = False, use_joblib: bool = False):
         self.logger_.info("Fitting local classifiers")
         nodes = self._get_parents()
-        self._fit_node_classifier(nodes, local_mode)
+        self._fit_node_classifier(nodes, local_mode, use_joblib)

tests/test_LocalClassifierPerLevel.py

@@ -9,7 +9,6 @@
 from sklearn.linear_model import LogisticRegression
 from sklearn.utils.estimator_checks import parametrize_with_checks
 from sklearn.utils.validation import check_is_fitted
-
 from hiclass import LocalClassifierPerLevel
 
 
@@ -60,16 +59,14 @@ def test_fit_digraph(digraph_logistic_regression):
 
 
 def test_fit_digraph_joblib_multiprocessing(digraph_logistic_regression):
-    LocalClassifierPerLevel._has_ray = False
-
     classifiers = [
         LogisticRegression(),
         LogisticRegression(),
     ]
     digraph_logistic_regression.n_jobs = 2
     digraph_logistic_regression.local_classifiers_ = classifiers
 
-    digraph_logistic_regression._fit_digraph(local_mode=True)
+    digraph_logistic_regression._fit_digraph(local_mode=True, use_joblib=True)
     for classifier in digraph_logistic_regression.local_classifiers_:
         try:
             check_is_fitted(classifier)

tests/test_LocalClassifierPerNode.py

@@ -112,15 +112,13 @@ def test_fit_digraph(digraph_logistic_regression):
 
 
 def test_fit_digraph_joblib_multiprocessing(digraph_logistic_regression):
-    LocalClassifierPerNode._has_ray = False
-
     classifiers = {
         "b": {"classifier": LogisticRegression()},
         "c": {"classifier": LogisticRegression()},
     }
     digraph_logistic_regression.n_jobs = 2
     nx.set_node_attributes(digraph_logistic_regression.hierarchy_, classifiers)
-    digraph_logistic_regression._fit_digraph(local_mode=True)
+    digraph_logistic_regression._fit_digraph(local_mode=True, use_joblib=True)
     with pytest.raises(KeyError):
         check_is_fitted(digraph_logistic_regression.hierarchy_.nodes["a"]["classifier"])
     for node in ["b", "c"]: