Merge pull request #44 from UNSW-CEEM/more-examples

More examples

docs/source/examples.md

@@ -5,4 +5,5 @@
 maxdepth: 2
 ---
 examples/visualising_p5min_demand_forecasts
+examples/p5min_demand_forecast_error_2021
 ```

docs/source/examples/visualising_p5min_demand_forecasts.md

@@ -7,7 +7,7 @@ jupytext:
     format_version: 0.13
     jupytext_version: 1.14.1
 kernelspec:
-  display_name: Python 3
+  display_name: Python 3 (ipykernel)
   language: python
   name: python3
 ---
@@ -74,6 +74,8 @@ Here we'll define our datetime range that we're interested in:
 ## Get demand forecast data for NSW
 
 ```{code-cell} ipython3
+:tags: [remove-output]
+
 p5_run_start, p5_run_end = generate_runtimes(start, end,
                                              "P5MIN")
 p5_data = compile_data(p5_run_start, p5_run_end, start, end,
@@ -107,6 +109,7 @@ hvhmap = p5_demand_forecasts.hvplot.heatmap(
 
 ```{code-cell} ipython3
 :tags: [remove-cell]
+
 pio.write_html(go.Figure(hvplot.render(hvhmap, backend="plotly")), "../_static/hvhmap.html")
 ```
 
@@ -123,6 +126,7 @@ file: ../_static/hvhmap.html
 To compare forecasts with actual demand data, we will use `NEMOSIS` to obtain actual demand data for NSW for this evening.
 
 ```{code-cell} ipython3
+:tags: [remove-output]
 # create a folder for NEMOSIS data
 nemosis_cache = Path("nemosis_cache/")
 if not nemosis_cache.exists():
@@ -213,6 +217,7 @@ fig = fig.update_layout(
 
 ```{code-cell} ipython3
 :tags: [remove-cell]
+
 pio.write_html(fig, "../_static/hvhmap+line.html")
 ```
 
@@ -237,6 +242,7 @@ run_lines = go.Figure(hvplot.render(run_time_iterations, backend="plotly"))
 
 ```{code-cell} ipython3
 :tags: [remove-cell]
+
 pio.write_html(run_lines, "../_static/run_lines.html")
 ```
 
@@ -276,6 +282,7 @@ overlay = overlay.update_layout(
 
 ```{code-cell} ipython3
 :tags: [remove-cell]
+
 pio.write_html(overlay, "../_static/cleaner_run_lines.html")
 ```
 
@@ -287,6 +294,7 @@ file: ../_static/cleaner_run_lines.html
 
 ```{code-cell} ipython3
 :tags: [remove-cell]
+
 for folder in ("./nemosis_cache/", "./nemseer_cache/"):
     folder = Path(folder)
     for file in folder.iterdir():

docs/source/index.md

@@ -5,7 +5,7 @@
 
 ```{toctree}
 ---
-maxdepth: 3
+maxdepth: 2
 caption: Contents
 ---
 quick_start

src/nemseer/downloader.py

@@ -220,6 +220,8 @@ def get_sqlloader_forecast_tables(
       - Removes numbering from enumerated tables for `P5MIN`
         - e.g. `CONSTRAINTSOLUTION(x)` are all reduced to `CONSTRAINTSOLUTION`
 
+    Examples:
+        See :ref:`querying table availability <quick_start:table availability>`
     Args:
         year: Year
         month: Month
@@ -248,7 +250,9 @@ def get_sqlloader_forecast_tables(
 
 def get_sqlloader_years_and_months() -> Dict[int, List[int]]:
     """Years and months with data on NEMWeb MMSDM Historical Data SQLLoader
-
+    Examples:
+        See :ref:`querying date ranges \
+        <quick_start:date range of available data>`
     Returns:
         Months mapped to each year. Data is available for each of these months.
     """

src/nemseer/forecast_type/run_time_generators.py

@@ -198,6 +198,10 @@ def generate_runtimes(
     may not be accurate for all :term:`forecast types`, e.g. :term:`MTPASA` which is not
     run at a set time.
 
+    Examples:
+        See :ref:`getting valid run times for a set of forecasted time \
+        <quick_start:getting valid run times for a set of forecasted times>`.
+
     Args:
         forecasted_start: Forecasts pertaining to times at or after this
             datetime are retained.

src/nemseer/nemseer.py

@@ -42,6 +42,9 @@ def download_raw_data(
     1. :attr:`run_start` and :attr:`run_end`
     2. :attr:`forecasted_start` and :attr:`forecasted_end`
 
+    Examples:
+        See :ref:`downloading raw data examples <quick_start:downloading raw data>`.
+
     Arguments:
         forecast_type: One of :data:`nemseer.forecast_types`
         tables: Table or tables required. A single table can be supplied as
@@ -135,7 +138,7 @@ def compile_data(
     For each queried table, this function:
 
     1. If required, downloads raw forecast data for the table and converts to the
-        requested data structure.
+       requested data structure.
     2. Otherwise, compiles table data from either of or both of the caches.
     3. Applies user-requested filtering to :term:`run times` and
        :term:`forecasted times` to any raw data.
@@ -144,6 +147,9 @@ def compile_data(
     If :attr:`data_format` = "df" (default), a :class:`pandas.DataFrame` is returned.
     Otherwise, if :attr:`data_format` = "xr", a :class:`xarray.Dataset` is returned.
 
+    Examples:
+        See :ref:`compiling data examples <quick_start:compiling data>`.
+
     Arguments:
         run_start: Forecast runs at or after this datetime are queried.
         run_end: Forecast runs before or at this datetime are queried.