Improve documentation (#134)

docs/api/estimators.md

@@ -1,17 +1,20 @@
 # Estimators
 
+The package implements a number of estimators with common API. For general usage instructions and examples, consult the [general instructions](../estimators.md).
+Although the API is organized alphabetically, the estimators have been grouped by types in the [list of estimators](../estimators.md#list-of-estimators) together with relevant literature.
+
 ::: bmi.estimators.CCAMutualInformationEstimator
 
+::: bmi.estimators.DonskerVaradhanEstimator
+
 ::: bmi.estimators.HistogramEstimator
 
+::: bmi.estimators.InfoNCEEstimator
+
 ::: bmi.estimators.KDEMutualInformationEstimator
 
 ::: bmi.estimators.KSGEnsembleFirstEstimator
 
-::: bmi.estimators.DonskerVaradhanEstimator
-
 ::: bmi.estimators.MINEEstimator
 
-::: bmi.estimators.InfoNCEEstimator
-
 ::: bmi.estimators.NWJEstimator

docs/api/index.md

@@ -3,3 +3,4 @@
 - [Tasks](tasks.md) represent named probability distributions which are used in the benchmark.
 - [Estimators](estimators.md) are the implemented mutual information estimators.
 - [Samplers](samplers.md) represent joint probability distributions with known mutual information from which one can sample. They are lower level than `Tasks` and can be used to define new tasks by transformations which preserve mutual information.
+- [Interfaces](interfaces.md) defines the main interfaces used in the package.

docs/api/interfaces.md

@@ -0,0 +1,3 @@
+## Interfaces
+This section explains the most important interfaces used in the package.
+

docs/contributing.md

@@ -28,7 +28,7 @@ To be able to reproduce a bug, we will usually need the following information:
 
 **Don't:**
 
-  - Don't include license information. This project is MIT licensed and by submitting your pull request you implicitly and irrevocably agree to use this.
+  - Don't include license information. This project uses the MIT license. By submitting your pull request you implicitly and irrevocably agree to using this license.
   - Don't implement too many ideas in a single pull request. Multiple features should be implemented in separate pull requests.
 
 

docs/estimators.md

@@ -0,0 +1,42 @@
+# Estimators
+
+The package supports a range of existing mutual information estimators. For the full list, see [below](#list-of-estimators).
+
+## General usage instructions
+
+## List of estimators
+
+### Neural estimators
+  - MINE[@belghazi:18:mine] estimator is implemented as [`MINEEstimator`](api/estimators.md#bmi.estimators.MINEEstimator).
+  - InfoNCE[@oord:18:infonce], also known as Contrastive Predictive Coding is implemented as [`InfoNCEEstimator`](api/estimators.md#bmi.estimators.InfoNCEEstimator).
+
+### Model-based estimators
+  - Canonical correlation analysis[@Brillinger-2004,@kay-elliptic]
+
+### Histogram-based estimators
+
+### Neighborhood-based estimators
+  - An ensemble of Kraskov-Stögbauer-Grassberger estimators[@kraskov:04:ksg] is implemented as [`KSGEnsembleFirstEstimator`](api/estimators.md#bmi.estimators.KSGEnsembleFirstEstimator).
+
+## FAQ
+
+### Do these estimators work for discrete variables?
+When both variables $X$ and $Y$ are discrete, we recommend the [`dit` package](https://github.com/dit/dit). When one variable is discrete and the other is continuous, one can approximate mutual information by adding small noise to the discrete variable. 
+
+!!! todo
+
+    Add a Python example showing how to add the noise.
+
+### Where is the API showing how to use the estimators?
+
+The API is [here](api/estimators.md).
+
+### How can I add a new estimator?
+Thank you for considering contributing to this project! Please, consult [contributing guidelines](contributing.md) and reach out to us on [GitHub](https://github.com/cbg-ethz/bmi/issues), so we can discuss the best way of adding the estimator to the package.
+Generally, the following steps are required:
+1. Implement the interface `IMutualInformationPointEstimator` in a new file inside `src/bmi/estimators` directory. The unit tests should be added in `tests/estimators` directory.
+2. Export the new estimator to the public API by adding an entry in `src/bmi/estimators/__init__.py`.
+3. Export the docstring of new estimator to `docs/api/estimators.md`.
+4. Add the estimator to the [list of estimators](#list-of-estimators).
+
+\bibliography

mkdocs.yml

@@ -37,9 +37,12 @@ plugins:
           options:
             show_source: false
             show_root_heading: true
+  - bibtex:
+      bib_file: 'references.bib'
 
 nav:
   - Home: index.md
+  - Estimators: estimators.md
   - Contributing: contributing.md
   - API: api/index.md
 

pyproject.toml

@@ -42,6 +42,7 @@ mkdocs-material = "^9.1.6"
 mkdocstrings = {extras = ["python"], version = "^0.21.2"}
 mkdocs-gen-files = "^0.4.0"
 mkdocs-literate-nav = "^0.6.0"
+mkdocs-bibtex = "^2.11.0"
 
 
 [build-system]