Update docs

Author: mwydmuch

README.md

@@ -40,13 +40,13 @@ We provide a short usage guide for the library in [short_usage_guide.ipynb](http
 You can also check the documentation for more details.
 
 
-## Methods, usage, and how to cite
+## Methods implemented in xCOLUMNs
 
 The library implements the following methods:
 
 ### Instance-wise weighted prediction
 
-The library implements a set of methods for instance-wise weighted prediction, that include optimal prediction strategies for different metrics, such as:
+The library implements a set of methods for instance-wise weighted prediction, that include optimal infernece strategies for some metrics, such as:
 - Precision at k
 - Propensity-scored precision at k
 - Macro-averaged recall at k
@@ -55,12 +55,14 @@ The library implements a set of methods for instance-wise weighted prediction, t
 
 ### Optimization of prediction for a given test set using Block Coordinate Ascent/Descent (BCA/BCD)
 
-The method aims to optimize the prediction for a given test set using the block coordinate ascent/descent algorithm.
+The method aims to optimize the prediction for a given metrics and test set using the block coordinate ascent/descent algorithm.
 
 The method was first introduced and described in the paper:
 > [Erik Schultheis, Marek Wydmuch, Wojciech Kotłowski, Rohit Babbar, Krzysztof Dembczyński. Generalized test utilities for long-tail performance in extreme multi-label classification. NeurIPS 2023.](https://arxiv.org/abs/2311.05081)
 
-### Finding optimal population classifier via Frank-Wolfe (FW)
+### Finding optimal population classifier using Frank-Wolfe (FW)
+
+The method finds the optimal population classifier for given metric using the Frank-Wolfe optimization algorithm on the provided training set.
 
 The method was first introduced and described in the paper:
 > [Erik Schultheis, Wojciech Kotłowski, Marek Wydmuch, Rohit Babbar, Strom Borman, Krzysztof Dembczyński. Consistent algorithms for multi-label classification with macro-at-k metrics. ICLR 2024.](https://arxiv.org/abs/2401.16594)
@@ -69,9 +71,9 @@ The method was first introduced and described in the paper:
 ## Repository structure
 
 The repository is organized as follows:
-- `docs/` - Sphinx documentation (work in progress)
-- `experiments/` - a code for reproducing experiments from the papers, see the README.md file in the directory for details
-- `xcolumns/` - Python package with the library
+- `docs/` - Sphinx documentation
+- `experiments/` - a code for reproducing experiments from the papers, see the README.md file in the directory for more details
+- `xcolumns/` - the library source code
 - `tests/` - tests for the library (the coverage is bit limited at the moment, but these test should guarantee that the main components of the library works as expected)
 
 

docs/api/block_coordinate.md

@@ -1,4 +1,4 @@
-# Block Coordinate-based prediction methods
+# Block Coordinate-based prediction methods (`xcolumns.block_coordinate`)
 
 `xcolumns.block_coordinate` module implements the methods for finding the optimal prediction for given test set using the Block Coordinate Ascend/Desend algorithm with 0-th order approximation of expected utility.
 The method was first introduced and described in the paper:
@@ -7,15 +7,15 @@ The method was first introduced and described in the paper:
 Note: BCA/BCD with 0-approximationuses tp, fp, fn, tn matrices parametrization of the confussion matrix,
 as opposed to algorithms presented in the paper, which use :math:`t, q, p` parametrization. However both algorithms are equivalent.
 
-The main function of the module is [**predict_using_bc_with_0approx**](#xcolumns.block_coordinate.predict_using_bc_with_0approx):
+The main function of the module is {func}`predict_using_bc_with_0approx() <xcolumns.block_coordinate.predict_using_bc_with_0approx>`:
 
 ```{eval-rst}
 .. autofunction:: xcolumns.block_coordinate.predict_using_bc_with_0approx
 ```
 
 ## Wrapper functions for specific metrics
 
-The module provides the wrapper functions for specific metrics that can be used as arguments for the `predict_using_bc_with_0approx` function as well as factory function for creating such wrapper functions.
+The module provides the wrapper functions for specific metrics that can be used as arguments for the {func}`predict_using_bc_with_0approx() <xcolumns.block_coordinate.predict_using_bc_with_0approx>` function as well as factory function for creating such wrapper functions.
 
 ```{eval-rst}
 .. automodule:: xcolumns.block_coordinate
@@ -28,7 +28,7 @@ The module provides the wrapper functions for specific metrics that can be used
 
 ## Special function for optimization of coverage
 
-The module provides the special function for optimization of coverage metric that use other way of estimating the expected value of the metric than `predict_using_bc_with_0approx` function.e
+The module provides the special function for optimization of coverage metric that use other way of estimating the expected value of the metric than {func}`predict_using_bc_with_0approx() <xcolumns.block_coordinate.predict_using_bc_with_0approx>` function.
 
 ```{eval-rst}
 .. autofunction:: xcolumns.block_coordinate.predict_optimizing_coverage_using_bc

docs/api/confusion_matrix.md

@@ -1,7 +1,9 @@
-# Confusion Matrix
+# Confusion Matrix (`xcolumns.confusion_matrix`)
 
 `xcolumns.confusion_matrix` module implements confusion matrix object and functions that can be used to calculate it.
 In xCOLUMNs, the confusion matrix is parametrized by four matrices: true positive (tp), false positive (fp), false negative (fn), and true negative (tn).
+The confusion matrix object can be used to calculate the metrics based on the confusion matrix.
+xCOLUMNs implements the popular metrics in [`xcolumns.metrics`](metrics) module.
 
 ```{eval-rst}
 .. automodule:: xcolumns.confusion_matrix

docs/api/frank_wolfe.md

@@ -1,11 +1,10 @@
-# Finding population classifiers using Frank Wolfe-based method
+# Finding population classifiers using Frank Wolfe-based method (`xcolumns.frank_wolfe`)
 
 `xcolumns.frank_wolfe` module implements the methods for finding the optimal population classifier using the Frank-Wolfe algorithm.
 The method was first introduced and described in the paper:
 > [Erik Schultheis, Wojciech Kotłowski, Marek Wydmuch, Rohit Babbar, Strom Borman, Krzysztof Dembczyński. Consistent algorithms for multi-label classification with macro-at-k metrics. ICLR 2024.](https://arxiv.org/abs/2401.16594)
 
-The main function of the module is [**find_classifier_using_fw**](#xcolumns.frank_wolfe.find_classifier_using_fw):
-
+The main function of the module is {func}`find_classifier_using_fw() <xcolumns.frank_wolfe.find_classifier_using_fw>`:
 
 ```{eval-rst}
 .. autofunction:: xcolumns.frank_wolfe.find_classifier_using_fw
@@ -14,7 +13,7 @@ The main function of the module is [**find_classifier_using_fw**](#xcolumns.fran
 
 The function returns the RandomizedWeightedClassifier object that can be used for prediction.
 The RandomizedWeightedClassifier is a set of weighted classifiers as defined in
-The module also provides the function [**predict_using_randomized_weighted_classifier**](#xcolumns.frank_wolfe.predict_using_randomized_weighted_classifier) for predicting the labels using the RandomizedWeightedClassifier object.
+The module also provides the function {func}`predict_using_randomized_weighted_classifier() <xcolumns.frank_wolfe.predict_using_randomized_weighted_classifier>` for predicting the labels using the RandomizedWeightedClassifier object.
 
 
 ```{eval-rst}
@@ -28,7 +27,7 @@ The module also provides the function [**predict_using_randomized_weighted_class
 
 ## Wrapper functions for specific metrics
 
-The module provides the wrapper functions for specific metrics that can be used as arguments for the `find_classifier_using_fw` function as well as factory function for creating such wrapper functions.
+The module provides the wrapper functions for specific metrics that can be used as arguments for the {func}`find_classifier_using_fw() <xcolumns.frank_wolfe.find_classifier_using_fw>` function as well as factory function for creating such wrapper functions.
 
 ```{eval-rst}
 .. automodule:: xcolumns.frank_wolfe

docs/api/metrics.md

@@ -1,7 +1,8 @@
-# Metrics
+# Metrics (`xcolumns.metrics`)
 
 `xcolumns.metrics` module implements a set of methods for calculating the metrics based on both the confusion matrix and the true and predicted labels.
-The methods calculating the metrics on the entries of the confusion matrix can be also used as arguments for the methods in the [`xcolumns.block_coordinate`](api/block_coordinate) and [`xcolumns.frank_wolfe`](api/frank_wolfe) modules.
+The methods calculating the metrics on the entries of the confusion matrix can be also used as arguments for the methods in the
+[`xcolumns.block_coordinate`](block_coordinate) and [`xcolumns.frank_wolfe`](frank_wolfe) modules.
 
 ```{eval-rst}
 .. automodule:: xcolumns.metrics

docs/api/weighted_prediction.md

@@ -1,7 +1,7 @@
-# Weighted predictions
+# Weighted predictions (`xcolumns.weighted_prediction`)
 
 `xcolumns.weighted_prediction` module provides the methods for calculating the weighted prediction for each instance based on the conditional probabilities of labels.
-The main function of the module is [**predict_weighted_per_instance**](#xcolumns.weighted_prediction.predict_weighted_per_instance).
+The main function of the module is {func}`predict_weighted_per_instance() <xcolumns.weighted_prediction.predict_weighted_per_instance>`.
 
 
 ```{eval-rst}
@@ -11,7 +11,7 @@ The main function of the module is [**predict_weighted_per_instance**](#xcolumns
 
 ## Prediction strategies based on weighted predictions
 
-Based on [**predict_weighted_per_instance**](#xcolumns.weighted_prediction.predict_weighted_per_instance) function the module provides few additional functions for calculating the predictions
+Based on {func}`predict_weighted_per_instance() <xcolumns.weighted_prediction.predict_weighted_per_instance>` function the module provides few additional functions for calculating the predictions
 that are optimal for some specific metrics or arbitrary upweight labels with smaller prior probabilities.
 
 ```{eval-rst}

docs/index.md

@@ -10,6 +10,13 @@ lastpage:
 
 # Welcome to xCOLUMNs documentation!
 
+xCOLUMNs stands for x**Consistent Optimization of Label-wise Utilities in Multi-label classificatioN**s.
+It is a small Python library that aims to implement different methods for the optimization of a general family of
+metrics that can be defined on multi-label classification matrices.
+These include, but are not limited to, label-wise metrics.
+The library provides an efficient implementation of the different optimization methods
+that easily scale to the extreme multi-label classification (XMLC) - problems with a very large number of labels and instances.
+
 
 ```{toctree}
 :hidden:

docs/intro/overview.md

@@ -1,10 +1,6 @@
 # Overview of xCOLUMNs library
 
-xCOLUMNs stands for x**Consistent Optimization of Label-wise Utilities in Multi-label classificatioN**s.
-It is a small Python library that aims to implement different methods for the optimization of a general family of
-metrics that can be defined on multi-label classification matrices.
-These include, but are not limited to, label-wise metrics (see below for details).
-The library provides an efficient implementation of the different optimization methods that easily scale to the extreme multi-label classification (XMLC) - problems with a very large number of labels and instances.
+
 
 
 ## What is multi-label classification?
@@ -43,9 +39,12 @@ In this sense xCOLUMNs implements plug-in inference methods, that can be used on
 
 The aim of xCOLUMNs is to provide methods for the optimization of the general family of label-wise utilities. Currently, the following methods are implemented:
 
-- Prediction for provided test set using **Block Coordinate Ascent/Descent (BC)** method, described in [1].
-- Search for optimal population classifier using **Frank-Wolfe (FW)** method, described in [2].
+- Weighted instance-wise prediction that include optimal infernece strategies for some metrics. Implemented in [`xcolumns.weighted_prediction`](../api/weighted_prediction) module.
+
+- Prediction for provided label-wise metric and test set using **Block Coordinate Ascent/Descent (BC)** method. Implemented in [`xcolumns.block_coordinate`](../api/block_coordinate) module. It was first introduced and described in:
+> [Erik Schultheis, Marek Wydmuch, Wojciech Kotłowski, Rohit Babbar, Krzysztof Dembczyński. Generalized test utilities for long-tail performance in extreme multi-label classification. NeurIPS 2023.](https://arxiv.org/abs/2311.05081)
 
-[1] [Erik Schultheis, Marek Wydmuch, Wojciech Kotłowski, Rohit Babbar, Krzysztof Dembczyński. Generalized test utilities for long-tail performance in extreme multi-label classification. NeurIPS 2023.](https://arxiv.org/abs/2311.05081)
+- Search for optimal population classifier for provided metric defined on mulit-label confusion matrix using **Frank-Wolfe (FW)** method and provided training set. Implemented in [`xcolumns.frank_wolfe`](../api/frank_wolfe) module. It was first introduced and described in:
+> [Erik Schultheis, Wojciech Kotłowski, Marek Wydmuch, Rohit Babbar, Strom Borman, Krzysztof Dembczyński. Consistent algorithms for multi-label classification with macro-at-k metrics. ICLR 2024.](https://arxiv.org/abs/2401.16594)
 
-[2] [Erik Schultheis, Wojciech Kotłowski, Marek Wydmuch, Rohit Babbar, Strom Borman, Krzysztof Dembczyński. Consistent algorithms for multi-label classification with macro-at-k metrics. ICLR 2024.](https://arxiv.org/abs/2401.16594)
+The library also implements a set of methods for calculating the metrics based on both the confusion matrix and the true and predicted labels. Implemented in [`xcolumns.confusion_matrix`](../api/confusion_matrix) and [`xcolumns.metrics`](../api/metrics) modules.

docs/intro/quick_start.md

@@ -16,4 +16,4 @@ However, the PyTorch is not a required dependency, so you need to install it sep
 
 ## Usage
 
-We provide a short usage guide for the library in [short_usage_guide.ipynb](https://github.com/mwydmuch/xCOLUMNs/blob/master/short_usage_guide.ipynb) notebook.
+We provide a short usage guide (with examples) for the library in [short_usage_guide.ipynb](https://github.com/mwydmuch/xCOLUMNs/blob/master/short_usage_guide.ipynb) notebook.

short_usage_guide.ipynb

@@ -96,7 +96,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "!pip install sklearn"
+    "!pip install sklearn matplotlib"
    ]
   },
   {
@@ -152,6 +152,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Cast the data to the desired type\n",
     "target_type = \"csr_matrix\"\n",
     "\n",
     "if target_type == \"torch\":\n",
@@ -267,7 +268,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Test top-k prediction\n",
     "from xcolumns.weighted_prediction import predict_top_k\n",
     "\n",
     "y_pred = predict_top_k(y_proba_test, k=3)\n",
@@ -312,7 +312,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Frank Wolfe\n",
     "from xcolumns.frank_wolfe import find_classifier_using_fw\n",
     "\n",
     "rnd_clf, meta = find_classifier_using_fw(\n",

xcolumns/__init__.py

@@ -1 +1 @@
-__version__ = "0.0.2"
+__version__ = "0.0.3"