Merge branch 'main' into cleanup_for_go_live

01_forecast.qmd

@@ -27,7 +27,7 @@ Unlike most scripts that concentrate the package imports at the beginning, this
 
 First, we will use `gingado` to run a simple example with the following characteristics:
 
-* selected currency pairs will be downloaded from the European Central Bank (ECB) servers using the [SDMX](www.sdmx.org) protocol
+* selected currency pairs will be downloaded from the European Central Bank (ECB) servers using the [SDMX](https://www.sdmx.org) protocol
     * these pairs will form our dependent variables in the models
 
 * using `gingado`, this series will be augmented with a time series on central bank policy rates and the interaction of rate changes and FX rate movements

CONTRIBUTING.md

@@ -22,6 +22,10 @@ To work with the documentation an tests, we use `quarto`. You can either use RSt
    - **For RStudio**: Quarto is integrated with RStudio. Ensure you have the latest version of RStudio to work with Quarto seamlessly.
    - **For Visual Studio Code**: Install the Quarto extension from the Visual Studio Code marketplace. This extension provides support for `.qmd` files, including syntax highlighting and preview capabilities.
 
+### Modifying the index page and README.md
+
+To modify the index page or the README.md file in the repository root, please only edit the index.qmd file. All changes in the index.qmd file will be rendered to the README.md file and moved automatically to the repository root via a post-render script `move_readme_to_root.py`.
+
 ### Reporting Issues and Suggestions
 
 If you encounter a bug, have suggestions, or want to propose new functionalities:

README.md

@@ -11,62 +11,72 @@ learning algorithms to more complex model pipelines used in production.
 `gingado` is a free, open source library built different
 functionalities:
 
--   [**data augmentation**](augmentation.html), to add more data from
-    official sources, improving the machine models being trained by the
-    user;
+- [**data
+  augmentation**](https://bis-med-it.github.io/gingado/augmentation.html),
+  to add more data from official sources, improving the machine models
+  being trained by the user;
 
--   **relevant** [**datasets**](datasets.html), both real and simulamed,
-    to allow for easier model development and comparison;
+- **relevant**
+  [**datasets**](https://bis-med-it.github.io/gingado/datasets.html),
+  both real and simulamed, to allow for easier model development and
+  comparison;
 
--   **automatic** [**benchmark model**](benchmark.html), to assess
-    candidate models against a reasonably well-performant model;
+- **automatic** [**benchmark
+  model**](https://bis-med-it.github.io/gingado/benchmark.html), to
+  assess candidate models against a reasonably well-performant model;
 
--   *(new!)* **machine learning-based**
-    [**estimators**](estimators.html), to help answer questions of
-    academic or practical importance;
+- *(new!)* **machine learning-based**
+  [**estimators**](https://bis-med-it.github.io/gingado/estimators.html),
+  to help answer questions of academic or practical importance;
 
--   **support for** [**model documentation**](documentation.html), to
-    embed documentation and ethical considerations in the model
-    development phase; and
+- **support for** [**model
+  documentation**](https://bis-med-it.github.io/gingado/documentation.html),
+  to embed documentation and ethical considerations in the model
+  development phase; and
 
--   [**utilities**](utils.html), including tools to allow for lagging
-    variables in a straightforward way.
+- [**utilities**](https://bis-med-it.github.io/gingado/utils.html),
+  including tools to allow for lagging variables in a straightforward
+  way.
 
 Each of these functionalities builds on top of the previous one. They
 can be used on a stand-alone basis, together, or even as part of a
 larger pipeline from data input to model training to documentation!
 
+<div>
+
 > **Tip**
 >
 > New functionalities are planned over time, so consider checking
 > frequently on `gingado` for the latest toolsets.
 
+</div>
+
 ## Design principles
 
 The choices made during development of `gingado` derive from the
 following principles, in no particular order:
 
--   **flexibility**: users can use `gingado` out of the box or build
-    custom processes on top of it;
+- **flexibility**: users can use `gingado` out of the box or build
+  custom processes on top of it;
 
--   **compatibility**: `gingado` works well with other widely used
-    libraries in machine learning, such as `scikit-learn` and `pandas`;
-    and
+- **compatibility**: `gingado` works well with other widely used
+  libraries in machine learning, such as `scikit-learn` and `pandas`;
+  and
 
--   **responsibility**: `gingado` facilitates and promotes model
-    documentation, including ethical considerations, as part of the
-    machine learning development workflow.
+- **responsibility**: `gingado` facilitates and promotes model
+  documentation, including ethical considerations, as part of the
+  machine learning development workflow.
 
 ## Acknowledgements
 
 `gingado`’s API is inspired on the following libraries:
 
--   `scikit-learn` (Buitinck et al. 2013)
+- `scikit-learn` (Buitinck et al. 2013)
 
--   `keras` (website [here](https://keras.io/about/) and also, [this
-    essay](https://medium.com/s/story/notes-to-myself-on-software-engineering-c890f16f4e4d))
+- `keras` (website [here](https://keras.io/about/) and also, [this
+  essay](https://medium.com/s/story/notes-to-myself-on-software-engineering-c890f16f4e4d))
 
--   `fastai` (Howard and Gugger 2020)
+- `fastai` (Howard and Gugger 2020)
 
 In addition, `gingado` is developed and maintained using
 [`quarto`](https://quarto.org/).
@@ -108,11 +118,23 @@ on economics and finance”, BIS Working Paper No 1122.
 
 ## References
 
+<div id="refs" class="references csl-bib-body hanging-indent">
+
+<div id="ref-sklearnAPI" class="csl-entry">
+
 Buitinck, Lars, Gilles Louppe, Mathieu Blondel, Fabian Pedregosa,
 Andreas Mueller, Olivier Grisel, Vlad Niculae, et al. 2013. “API Design
 for Machine Learning Software: Experiences from the Scikit-Learn
 Project.” *CoRR* abs/1309.0238. <http://arxiv.org/abs/1309.0238>.
 
+</div>
+
+<div id="ref-fastaiAPI" class="csl-entry">
+
 Howard, Jeremy, and Sylvain Gugger. 2020. “Fastai: A Layered API for
 Deep Learning.” *Information* 11 (2).
 <https://doi.org/10.3390/info11020108>.
+
+</div>
+
+</div>

_quarto.yml

@@ -1,6 +1,8 @@
 project:
   type: website
   output-dir: docs
+  post-render: 
+    - move_readme_to_root.py
 
 format:
   html:

docs/forecast.html

@@ -283,7 +283,7 @@ <h2 id="toc-title">On this page</h2>
 <p>Unlike most scripts that concentrate the package imports at the beginning, this walkthrough will import as needed, to better highlight where each contribution of <code>gingado</code> is used in the workflow.</p>
 <p>First, we will use <code>gingado</code> to run a simple example with the following characteristics:</p>
 <ul>
-<li><p>selected currency pairs will be downloaded from the European Central Bank (ECB) servers using the <a href="www.sdmx.org">SDMX</a> protocol</p>
+<li><p>selected currency pairs will be downloaded from the European Central Bank (ECB) servers using the <a href="https://www.sdmx.org">SDMX</a> protocol</p>
 <ul>
 <li>these pairs will form our dependent variables in the models</li>
 </ul></li>
@@ -1534,7 +1534,7 @@ <h2 class="anchored" data-anchor-id="references">References</h2>
 <span id="cb43-27"><a href="#cb43-27" aria-hidden="true" tabindex="-1"></a></span>
 <span id="cb43-28"><a href="#cb43-28" aria-hidden="true" tabindex="-1"></a>First, we will use <span class="in">`gingado`</span> to run a simple example with the following characteristics:</span>
 <span id="cb43-29"><a href="#cb43-29" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb43-30"><a href="#cb43-30" aria-hidden="true" tabindex="-1"></a><span class="ss">* </span>selected currency pairs will be downloaded from the European Central Bank (ECB) servers using the <span class="co">[</span><span class="ot">SDMX</span><span class="co">](www.sdmx.org)</span> protocol</span>
+<span id="cb43-30"><a href="#cb43-30" aria-hidden="true" tabindex="-1"></a><span class="ss">* </span>selected currency pairs will be downloaded from the European Central Bank (ECB) servers using the <span class="co">[</span><span class="ot">SDMX</span><span class="co">](https://www.sdmx.org)</span> protocol</span>
 <span id="cb43-31"><a href="#cb43-31" aria-hidden="true" tabindex="-1"></a><span class="ss">    * </span>these pairs will form our dependent variables in the models</span>
 <span id="cb43-32"><a href="#cb43-32" aria-hidden="true" tabindex="-1"></a></span>
 <span id="cb43-33"><a href="#cb43-33" aria-hidden="true" tabindex="-1"></a><span class="ss">* </span>using <span class="in">`gingado`</span>, this series will be augmented with a time series on central bank policy rates and the interaction of rate changes and FX rate movements</span>

docs/index.html

@@ -228,12 +228,12 @@ <h1 class="title">Welcome to gingado!</h1>
 <h2 class="anchored" data-anchor-id="overview">Overview</h2>
 <p><code>gingado</code> is a free, open source library built different functionalities:</p>
 <ul>
-<li><p><a href="augmentation.html"><strong>data augmentation</strong></a>, to add more data from official sources, improving the machine models being trained by the user;</p></li>
-<li><p><strong>relevant</strong> <a href="datasets.html"><strong>datasets</strong></a>, both real and simulamed, to allow for easier model development and comparison;</p></li>
-<li><p><strong>automatic</strong> <a href="benchmark.html"><strong>benchmark model</strong></a>, to assess candidate models against a reasonably well-performant model;</p></li>
-<li><p><em>(new!)</em> <strong>machine learning-based</strong> <a href="estimators.html"><strong>estimators</strong></a>, to help answer questions of academic or practical importance;</p></li>
-<li><p><strong>support for</strong> <a href="documentation.html"><strong>model documentation</strong></a>, to embed documentation and ethical considerations in the model development phase; and</p></li>
-<li><p><a href="utils.html"><strong>utilities</strong></a>, including tools to allow for lagging variables in a straightforward way.</p></li>
+<li><p><a href="https://bis-med-it.github.io/gingado/augmentation.html"><strong>data augmentation</strong></a>, to add more data from official sources, improving the machine models being trained by the user;</p></li>
+<li><p><strong>relevant</strong> <a href="https://bis-med-it.github.io/gingado/datasets.html"><strong>datasets</strong></a>, both real and simulamed, to allow for easier model development and comparison;</p></li>
+<li><p><strong>automatic</strong> <a href="https://bis-med-it.github.io/gingado/benchmark.html"><strong>benchmark model</strong></a>, to assess candidate models against a reasonably well-performant model;</p></li>
+<li><p><em>(new!)</em> <strong>machine learning-based</strong> <a href="https://bis-med-it.github.io/gingado/estimators.html"><strong>estimators</strong></a>, to help answer questions of academic or practical importance;</p></li>
+<li><p><strong>support for</strong> <a href="https://bis-med-it.github.io/gingado/documentation.html"><strong>model documentation</strong></a>, to embed documentation and ethical considerations in the model development phase; and</p></li>
+<li><p><a href="https://bis-med-it.github.io/gingado/utils.html"><strong>utilities</strong></a>, including tools to allow for lagging variables in a straightforward way.</p></li>
 </ul>
 <p>Each of these functionalities builds on top of the previous one. They can be used on a stand-alone basis, together, or even as part of a larger pipeline from data input to model training to documentation!</p>
 <div class="callout callout-style-default callout-tip callout-titled">

index.qmd

@@ -1,6 +1,11 @@
 ---
 description: A machine learning library for economics and finance
-output-file: index.html
+format:
+  html:
+    output-file: index.html
+  gfm:
+    output-file: README.md
+format-links: false
 title: Welcome to gingado!
 jupyter: python3
 ---
@@ -12,21 +17,21 @@ jupyter: python3
 
 `gingado` is a free, open source library built different functionalities:
 
-* [**data augmentation**](augmentation.html), to add more data from official sources, improving the machine models being trained by the user;
+* [**data augmentation**](https://bis-med-it.github.io/gingado/augmentation.html), to add more data from official sources, improving the machine models being trained by the user;
 
-* **relevant** [**datasets**](datasets.html), both real and
+* **relevant** [**datasets**](https://bis-med-it.github.io/gingado/datasets.html), both real and
   simulamed, to allow for easier model development and comparison;
 
-* **automatic** [**benchmark model**](benchmark.html), to assess
+* **automatic** [**benchmark model**](https://bis-med-it.github.io/gingado/benchmark.html), to assess
   candidate models against a reasonably well-performant model;
 
-* *(new!)* **machine learning-based** [**estimators**](estimators.html), to help answer questions of academic or practical importance;
+* *(new!)* **machine learning-based** [**estimators**](https://bis-med-it.github.io/gingado/estimators.html), to help answer questions of academic or practical importance;
 
-* **support for** [**model documentation**](documentation.html), to
+* **support for** [**model documentation**](https://bis-med-it.github.io/gingado/documentation.html), to
   embed documentation and ethical considerations in the model
   development phase; and
 
-* [**utilities**](utils.html), including tools to allow for lagging variables in a straightforward way.
+* [**utilities**](https://bis-med-it.github.io/gingado/utils.html), including tools to allow for lagging variables in a straightforward way.
 
 Each of these functionalities builds on top of the previous one. They can be used on a stand-alone basis, together, or even as part of a larger pipeline from data input to model training to documentation!
 

move_readme_to_root.py

@@ -0,0 +1,17 @@
+"""This script moves the README.md file from the docs folder into the project
+root. This is required, since the index.qmd file can only be rendered into
+files within the output folder. The post render option of the index.qmd file
+will then call this script to move it."""
+import os
+import shutil
+
+root_path = os.path.dirname(os.path.abspath(__file__))
+source_path = os.path.join(root_path, 'docs', 'README.md')
+destination_path = os.path.join(root_path, 'README.md')
+
+if os.path.exists(source_path):
+    # Move the file
+    try:
+        shutil.move(source_path, destination_path)
+    except Exception as e:
+        print(f"Error moving README.md file to project root: {e}")