From 0f6c59d7c2e03c6f20ce3da6f72ec56723573888 Mon Sep 17 00:00:00 2001
From: Tom Kralidis <tomkralidis@gmail.com>
Date: Wed, 9 Oct 2024 06:16:19 -0400
Subject: [PATCH] add WIS2 GDC practical exercise

---
 .../discovering-datasets-from-wis2-gdc.md     | 116 ++++++++++++++++++
 documentation/mkdocs.yml                      |   1 +
 2 files changed, 117 insertions(+)
 create mode 100644 documentation/docs/practical-sessions/discovering-datasets-from-wis2-gdc.md

diff --git a/documentation/docs/practical-sessions/discovering-datasets-from-wis2-gdc.md b/documentation/docs/practical-sessions/discovering-datasets-from-wis2-gdc.md
new file mode 100644
index 00000000..e2696635
--- /dev/null
+++ b/documentation/docs/practical-sessions/discovering-datasets-from-wis2-gdc.md
@@ -0,0 +1,116 @@
+---
+title: Discovering datasets from the WIS2 Global Discovery Catalogue
+---
+
+# Discovering datasets from the WIS2 Global Discovery Catalogue
+
+!!! abstract "Learning outcomes!"
+
+    By the end of this practical session, you will be able to:
+
+    - use pywiscat to discover datasets from the Global Discovery Catalogue
+
+## Introduction
+
+In this session you will learn how to discover data from the WIS2 Global Discovery Catalogue (GDC).
+
+At the moment, the following GDCs are available:
+
+- Environment and Climate Change Canada, Meteorological Service of Canada: <https://wis2-gdc.weather.gc.ca>
+- China Meteorological Administration: <https://gdc.wis.cma.cn/api>
+- Deutscher Wetterdienst: <https://wis2.dwd.de/gdc>
+
+For this exercise, we will use the WIS2 GDC setup as part of the training, found at <http://192.168.7.153>.
+
+## Preparation
+
+!!! note
+    Before starting please login to your student VM.
+
+## Installing pywiscat
+
+Use the `pip3` Python package installer to install pywiscat on your VM:
+```bash
+pip3 install pywiscat
+```
+
+Verify that the installation was successful:
+
+```bash
+pywiscat --version
+```
+
+## Finding data with pywiscat
+
+By default, pywiscat connects to Canada's Global Discovery Catalogue.  Let's configure pywiscat to query the training GDC by setting the `PYWISCAT_GDC_URL` environment variable:
+
+```bash
+export PYWISCAT_GDC_URL=http://192.168.7.153
+```
+
+Let's use [pywiscat](https://github.com/wmo-im/pywiscat) to query the GDC setup as part of the training.
+
+```bash
+pywiscat search --help
+```
+
+Now search the GDC for all records:
+
+```bash
+pywiscat search
+```
+
+!!! question
+
+    How many records are returned from the search?
+
+??? success "Click to reveal answer"
+    There should be over 40 records returned
+
+Let's try querying the GDC with a keyword:
+
+```bash
+pywiscat search -q observations
+```
+
+!!! question
+
+    What is the data policy of the results?
+
+??? success "Click to reveal answer"
+    All data returned should specify "core" data
+
+Try additional queries with `-q`
+
+!!! tip
+
+    The `-q` flag allows for the following syntax:
+
+    - `-q synop`: find all records with the word "synop"
+    - `-q temp`: find all records with the word "temp"
+    - `-q "observations AND fiji"`: find all records with the words "observations" and "fiji"
+    - `-q "observations NOT fiji"`: find all records that contain the word "observations" but not the word "fiji"
+    - `-q "synop OR temp"`: find all records with both "synop" or "temp"
+    - `-q "obs~"`: fuzzy search
+
+    When searching for terms with spaces, enclose in double quotes.
+
+Let's get more details on a specific search result that we are interested in:
+
+```bash
+pywiscat get <id>
+```
+
+!!! tip
+
+    Use the `id` value from the previous search.
+
+
+## Conclusion
+
+!!! success "Congratulations!"
+
+    In this practical session, you learned how to:
+
+    - use pywiscat to discover datasets from the WIS2 Global Discovery Catalogue
+
diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml
index cc5ffeaa..8c39f126 100644
--- a/documentation/mkdocs.yml
+++ b/documentation/mkdocs.yml
@@ -25,6 +25,7 @@ nav:
         - Adding GTS-headers to WIS2 notifications: practical-sessions/adding-gts-headers-to-wis2-notifications.md
         - Setting up a recommended dataset with access control: practical-sessions/datasets-with-access-control.md
         - Downloading data from WIS2: practical-sessions/downloading-data-from-wis2.md
+        - Discovering datasets from the WIS2 Global Discovery Catalogue: practical-sessions/discovering-datasets-from-wis2-gdc.md
         #- Querying data using the wis2box API: practical-sessions/querying-data-using-the-wis2box-api.md
         #- Working with BUFR data: practical-sessions/bufr-command-line-tools.md
     - Cheatsheets: