update README; conftest for rst; workflow build docs; logging

Author: Hông-Lan Botterman

.coveragerc

@@ -0,0 +1,30 @@
+name: Build Docs
+
+on:
+  pull_request:
+    branches:
+      - main
+      - dev
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: 1.8.3
+      - name: Lock
+        run: poetry lock --no-update
+      - name: Install
+        run: poetry install
+      - name: Build Docs
+        run: |
+          poetry run sphinx-build -b html docs/ _build/html

.github/workflows/docs.yml

@@ -70,14 +70,13 @@ With just these few lines of code, you can see how easy it is to
   from qolmat.utils import data
 
   # load and prepare csv data
-
   df_data = data.get_data("Beijing")
   columns = ["TEMP", "PRES", "WSPM"]
   df_data = df_data[columns]
   df_with_nan = data.add_holes(df_data, ratio_masked=0.2, mean_size=120)
 
   # impute and compare
-  imputer_mean = imputers.ImputerMean(groups=("station",))
+  imputer_mean = imputers.ImputerSimple(strategy="mean", groups=("station",))
   imputer_interpol = imputers.ImputerInterpolation(method="linear", groups=("station",))
   imputer_var1 = imputers.ImputerEM(model="VAR", groups=("station",), method="mle", max_iter_em=50, n_iter_ou=15, dt=1e-3, p=1)
   dict_imputers = {
@@ -90,7 +89,7 @@ With just these few lines of code, you can see how easy it is to
         dict_imputers,
         columns,
         generator_holes = generator_holes,
-        metrics = ["mae", "wmape", "KL_columnwise", "ks_test", "energy"],
+        metrics = ["mae", "wmape", "kl_columnwise", "ks_test", "energy"],
     )
   results = comparison.compare(df_with_nan)
   results.style.highlight_min(color="lightsteelblue", axis=1)

README.rst

@@ -37,6 +37,9 @@ clean:
 	-rm -rf examples/tutorials/*
 	-rm -rf generated/*
 
+doctest:
+	$(SPHINXBUILD) -b doctest . _build/doctest
+
 html:
 	# These two lines make the build a bit more lengthy, and the
 	# the embedding of images more robust

docs/Makefile

@@ -159,6 +159,11 @@
     "reference_url": {"qolmat": None},
 }
 
+suppress_warnings = ["autosectionlabel.*"]
+
+# doctest configuration
+doctest_test_doctest_blocks = "default"
+
 html_css_files = [
     "custom.css",
 ]

docs/conf.py

@@ -185,7 +185,7 @@ Concretely, the comparator takes as input a dataframe to impute, a proportion of
 Note these metrics compute reconstruction errors; it tells nothing about the distances between the "true" and "imputed" distributions.
 
 ```python tags=[]
-metrics = ["mae", "wmape", "KL_columnwise", "frechet"]
+metrics = ["mae", "wmape", "kl_columnwise", "frechet"]
 comparison = comparator.Comparator(
     dict_imputers,
     cols_to_impute,

examples/RPCA.md

@@ -124,7 +124,7 @@
     dict_imputers,
     cols_to_impute,
     generator_holes=generator_holes,
-    metrics=["mae", "wmape", "KL_columnwise", "wasserstein_columnwise"],
+    metrics=["mae", "wmape", "kl_columnwise", "wasserstein_columnwise"],
     max_evals=10,
 )
 results = comparison.compare(df)
@@ -133,7 +133,7 @@
 # %%
 # We have considered four metrics for comparison.
 # ``mae`` and ``wmape`` are point-wise metrics,
-# while ``KL_columnwise`` and ``wasserstein_columnwise`` are metrics
+# while ``kl_columnwise`` and ``wasserstein_columnwise`` are metrics
 # that compare distributions.
 # Since we treat time series with strong seasonal patterns, imputation
 # on residuals works very well.