Handle inline math equations

mkdocstrings_parser/parser.py

@@ -10,7 +10,6 @@
 # Suppress griffe warnings
 logging.getLogger("griffe").setLevel(logging.ERROR)
 
-
 class MkDocstringsParser:
     def __init__(self):
         pass
@@ -136,6 +135,18 @@ def generate_documentation(self, module_path: str, options: Dict[str, Any]) -> s
             markdown_docs = render_object_docs(obj, config)  # type: ignore
 
             markdown_docs = markdown_docs.replace(f"### `{to_replace}.", "### `")
+            # Fix double backslashes in inline math equations
+            markdown_docs = re.sub(
+                r"\$([^$]+)\$",
+                lambda m: "$" + m.group(1).replace("\\\\", "\\") + "$",
+                markdown_docs
+            )
+            # Fix underscores in inline math equations
+            markdown_docs = re.sub(
+                r"\$([^$]+)\$",
+                lambda m: "$" + m.group(1).replace("\_", "_") + "$",
+                markdown_docs
+            )
 
             return markdown_docs
 

pyproject.toml

@@ -7,9 +7,9 @@ name = "mkdocstrings-parser"
 version = "0.0.1"
 description = "A simple parser for mkdocstrings signature blocks"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 dependencies = [
-    "griffe2md<1.3",
+    "griffe2md",
     "pip-licenses>=4.5.1",
     "pyyaml",
     "rich",
@@ -19,16 +19,18 @@ dependencies = [
 dev = [
     "pytest",
     "pytest-cov",
+    "lightgbm<4.6"
 ]
 nixtlaverse = [
-    "coreforecast",
-    "utilsforecast",
-    "datasetsforecast",
-    "mlforecast[dask]",
-    "hierarchicalforecast",
-    "neuralforecast",
-    "statsforecast",
-    "nixtla"
+    "coreforecast@git+https://github.com/Nixtla/coreforecast.git",
+    "utilsforecast@git+https://github.com/Nixtla/utilsforecast.git",
+    "datasetsforecast@git+https://github.com/Nixtla/datasetsforecast.git",
+    "mlforecast[dask]@git+https://github.com/Nixtla/mlforecast.git",
+    "mlforecast@git+https://github.com/Nixtla/mlforecast.git",
+    "hierarchicalforecast@git+https://github.com/Nixtla/hierarchicalforecast.git@fix/docs",
+    "neuralforecast@git+https://github.com/Nixtla/neuralforecast.git",
+    "statsforecast@git+https://github.com/Nixtla/statsforecast.git",
+    "nixtla@git+https://github.com/Nixtla/nixtla.git"
 ]
 optional = ["pandas"]
 

tests/test_datasetsforecast.py

@@ -51,13 +51,7 @@ def test_yearly_dataclass(setup_parser):
 
 @pytest.mark.datasets
 def test_download_file(setup_parser):
-    fn = """::: datasetsforecast.utils.download_file
-    handler: python
-    options:
-      docstring_style: numpy
-      heading_level: 3
-      show_root_heading: true
-      show_source: true"""
+    fn = "::: datasetsforecast.utils.download_file"
     rendered = setup_parser.process_markdown(fn)
 
     assert rendered == """### `download_file`
@@ -72,7 +66,7 @@ def test_download_file(setup_parser):
 
 Name | Type | Description | Default
 ---- | ---- | ----------- | -------
-`directory` | <code>[str](#str)</code> | Custom directory where data will be downloaded. | *required*
+`directory` | <code>([str](#str), [Path](#pathlib.Path))</code> | Custom directory where data will be downloaded. | *required*
 `source_url` | <code>[str](#str)</code> | URL where data is hosted. | *required*
 `decompress` | <code>[bool](#bool)</code> | Wheter decompress downloaded file. Default False. | <code>False</code>
 """

tests/test_hierarchicalforecast.py

@@ -167,7 +167,7 @@ def test_bottomup(setup_parser):
 the first time by Orcutt in 1968.
 The corresponding hierarchical "projection" matrix is defined as:
 $$
-\\\\mathbf{P}_{\\\\text{BU}} = \\[\\\\mathbf{0}_{\\\\mathrm{[b],[a]}};|;\\\\mathbf{I}\\_{\\\\mathrm{[b][b]}}\\]
+\\mathbf{P}_{\\text{BU}} = \[\\mathbf{0}_{\\mathrm{[b],[a]}};|;\\mathbf{I}\_{\\mathrm{[b][b]}}\]
 $$
 
 <details class="references" open markdown="1">
@@ -235,4 +235,108 @@ def test_bottomup(setup_parser):
 Name | Type | Description
 ---- | ---- | -----------
 `dict` | | y_tilde: Reconciliated y_hat using the Bottom Up approach.
-"""
+"""
+
+def test_topdown(setup_parser):
+    fn = """::: hierarchicalforecast.methods.TopDown
+    handler: python
+    options:
+      docstring_style: google
+      members:
+        - fit
+        - predict
+        - fit_predict
+        - sample
+      inherited_members: false
+      heading_level: 3
+      show_root_heading: true
+      show_source: true"""
+    output = setup_parser.process_markdown(fn)
+    assert output == """### `TopDown`
+
+```python
+TopDown(method)
+```
+
+Bases: <code>[HReconciler](#hierarchicalforecast.methods.HReconciler)</code>
+
+Top Down Reconciliation Class.
+
+The Top Down hierarchical reconciliation method, distributes the total aggregate predictions and decomposes
+it down the hierarchy using proportions $\mathbf{p}_{\mathrm{[b]}}$ that can be actual historical values
+or estimated.
+
+```math
+\mathbf{P}=[\mathbf{p}_{\mathrm{[b]}}\;|\;\mathbf{0}_{\mathrm{[b][a,b\;-1]}}]
+```
+
+**Parameters:**
+
+Name | Type | Description | Default
+---- | ---- | ----------- | -------
+`method` | <code>[str](#str)</code> | One of `forecast_proportions`, `average_proportions` and `proportion_averages`. | *required*
+
+References:
+
+- [CW. Gross (1990). "Disaggregation methods to expedite product line forecasting". Journal of Forecasting, 9 , 233-254. doi:10.1002/for.3980090304](https://onlinelibrary.wiley.com/doi/abs/10.1002/for.3980090304).
+- [G. Fliedner (1999). "An investigation of aggregate variable time series forecast strategies with specific subaggregate time series statistical correlation". Computers and Operations Research, 26 , 1133-1149. doi:10.1016/S0305-0548(99)00017-9](<https://doi.org/10.1016/S0305-0548(99)00017-9>).
+
+#### `TopDown.fit`
+
+```python
+fit(S, y_hat, y_insample, y_hat_insample=None, sigmah=None, intervals_method=None, num_samples=None, seed=None, tags=None, idx_bottom=None)
+```
+
+TopDown Fit Method.
+
+**Parameters:**
+
+Name | Type | Description | Default
+---- | ---- | ----------- | -------
+`S` | <code>[ndarray](#numpy.ndarray)</code> | Summing matrix of size (`base`, `bottom`). | *required*
+`y_hat` | <code>[ndarray](#numpy.ndarray)</code> | Forecast values of size (`base`, `horizon`). | *required*
+`y_insample` | <code>[ndarray](#numpy.ndarray)</code> | Insample values of size (`base`, `insample_size`). Optional for `forecast_proportions` method. | *required*
+`y_hat_insample` | <code>[ndarray](#numpy.ndarray)</code> | Insample forecast values of size (`base`, `insample_size`). Optional for `forecast_proportions` method. | <code>None</code>
+`sigmah` | <code>[ndarray](#numpy.ndarray)</code> | Estimated standard deviation of the conditional marginal distribution. | <code>None</code>
+`interval_method` | <code>[str](#str)</code> | Sampler for prediction intervals, one of `normality`, `bootstrap`, `permbu`. | *required*
+`num_samples` | <code>[int](#int)</code> | Number of samples for probabilistic coherent distribution. | <code>None</code>
+`seed` | <code>[int](#int)</code> | Seed for reproducibility. | <code>None</code>
+`tags` | <code>[dict](#dict)\[[str](#str), [ndarray](#numpy.ndarray)\]</code> | Each key is a level and each value its `S` indices. | <code>None</code>
+`idx_bottom` | <code>[ndarray](#numpy.ndarray)</code> | Indices corresponding to the bottom level of `S`, size (`bottom`). | <code>None</code>
+
+**Returns:**
+
+Name | Type | Description
+---- | ---- | -----------
+`TopDown` | <code>[object](#object)</code> | fitted reconciler.
+
+#### `TopDown.fit_predict`
+
+```python
+fit_predict(S, y_hat, tags, idx_bottom=None, y_insample=None, y_hat_insample=None, sigmah=None, level=None, intervals_method=None, num_samples=None, seed=None)
+```
+
+Top Down Reconciliation Method.
+
+**Parameters:**
+
+Name | Type | Description | Default
+---- | ---- | ----------- | -------
+`S` | <code>[ndarray](#numpy.ndarray)</code> | Summing matrix of size (`base`, `bottom`). | *required*
+`y_hat` | <code>[ndarray](#numpy.ndarray)</code> | Forecast values of size (`base`, `horizon`). | *required*
+`tags` | <code>[dict](#dict)\[[str](#str), [ndarray](#numpy.ndarray)\]</code> | Each key is a level and each value its `S` indices. | *required*
+`idx_bottom` | <code>[ndarray](#numpy.ndarray)</code> | Indices corresponding to the bottom level of `S`, size (`bottom`). Default is None. | <code>None</code>
+`y_insample` | <code>[ndarray](#numpy.ndarray)</code> | Insample values of size (`base`, `insample_size`). Optional for `forecast_proportions` method. Default is None. | <code>None</code>
+`y_hat_insample` | <code>[ndarray](#numpy.ndarray)</code> | Insample forecast values of size (`base`, `insample_size`). Optional for `forecast_proportions` method. Default is None. | <code>None</code>
+`sigmah` | <code>[ndarray](#numpy.ndarray)</code> | Estimated standard deviation of the conditional marginal distribution. Default is None. | <code>None</code>
+`level` | <code>[list](#list)\[[int](#int)\]</code> | float list 0-100, confidence levels for prediction intervals. Default is None. | <code>None</code>
+`intervals_method` | <code>[str](#str)</code> | Sampler for prediction intervals, one of `normality`, `bootstrap`, `permbu`. Default is None. | <code>None</code>
+`num_samples` | <code>[int](#int)</code> | Number of samples for probabilistic coherent distribution. Default is None. | <code>None</code>
+`seed` | <code>[int](#int)</code> | Seed for reproducibility. | <code>None</code>
+
+**Returns:**
+
+Name | Type | Description
+---- | ---- | -----------
+`y_tilde` | <code>[ndarray](#numpy.ndarray)</code> | Reconciliated y_hat using the Top Down approach.
+"""

tests/test_utilsforecast.py

@@ -12,7 +12,7 @@ def test_utilsforecast_rmae(setup_parser):
     assert output == """### `rmae`
 
 ```python
-rmae(df, models, baseline, id_col='unique_id', target_col='y')
+rmae(df, models, baseline, id_col='unique_id', target_col='y', cutoff_col='cutoff')
 ```
 
 Relative Mean Absolute Error (RMAE)
@@ -30,10 +30,11 @@ def test_utilsforecast_rmae(setup_parser):
 `baseline` | <code>[str](#str)</code> | Column that identifies the baseline model predictions. | *required*
 `id_col` | <code>[str](#str)</code> | Column that identifies each serie. Defaults to 'unique_id'. | <code>'unique_id'</code>
 `target_col` | <code>[str](#str)</code> | Column that contains the target. Defaults to 'y'. | <code>'y'</code>
+`cutoff_col` | <code>[str](#str)</code> | Column that identifies the cutoff point for each forecast cross-validation fold. Defaults to 'cutoff'. | <code>'cutoff'</code>
 
 **Returns:**
 
 Type | Description
 ---- | -----------
-<code>[DFType](#utilsforecast.compat.DFType)</code> | pandas or polars DataFrame: dataframe with one row per id and one column per model.
+<code>[IntoDataFrameT](#narwhals.stable.v2.typing.IntoDataFrameT)</code> | pandas or polars DataFrame: dataframe with one row per id and one column per model.
 """