Prepare new release (#55)

* Update environment * Update docs env * Update env * update build * update build * update build * update build * Update docs * Update changelog
TUW-GEO · Dec 2, 2022 · aa651af · aa651af
1 parent 2de9c0e
commit aa651af
Show file tree

Hide file tree

Showing 7 changed files with 62 additions and 50 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,16 +1,12 @@
 version: 2
 
+build:
+  os: ubuntu-20.04
+  tools:
+    python: mambaforge-4.10
+
 sphinx:
   configuration: docs/conf.py
 
-submodules:
-  include: all
-
 conda:
-  environment: environment.yml
-
-python:
-  version: 3.7
-  install:
-    - method: pip
-      path: .
+  environment: docs/docs_env.yml
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -7,6 +7,14 @@ Unreleased
 
 -
 
+Version 1.3.0
+=============
+
+- Add module to assign custom metadata readers to ISMN_Interface
+- Notebook added that describes using a custom metadata reader
+- RTD build uses a separate, smaller environment.yml now (and mamba)
+
+
 Version 1.2.0
 =============
 

diff --git a/README.rst b/README.rst
@@ -23,11 +23,12 @@ The full documentation is available at https://ismn.readthedocs.io and includes
 a tutorial on reading ISMN data in python after downloading it from
 https://ismn.earth
 
+
 The following tutorials are available in ``docs/examples``:
 
- `1) ISMN reader basic functionality <https://ismn.readthedocs.io/en/latest/examples/interface.html>`_
+ `1) ISMN reader basic functionality <examples/interface.html>`_
 
- `2) Adding custom metadata readers <https://ismn.readthedocs.io/en/latest/examples/custom_meta.html>`_
+ `2) Adding custom metadata readers <examples/custom_meta.html>`_
 
 Citation
 ========

diff --git a/docs/docs_env.yml b/docs/docs_env.yml
@@ -0,0 +1,11 @@
+# To keep the RTD build as small as possible, we define a separate .yml here
+name: ismn_docs
+channels:
+- conda-forge
+- defaults
+dependencies:
+- python=3.8
+- ipykernel
+- nbsphinx
+# Note: RTD will add packages it needs automatically such as sphinx, sphinx_rtd_theme
+
diff --git a/docs/examples/custom_meta.ipynb b/docs/examples/custom_meta.ipynb
@@ -1,64 +1,61 @@
 {
  "cells": [
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "b962a0f0-65d9-4938-9de8-60667a12fa5e",
+   "cell_type": "markdown",
+   "id": "5f97f9c6-5263-4345-b155-398d4e51f873",
    "metadata": {},
-   "outputs": [],
    "source": [
     "# Add and use custom metadata in python_metadata"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": 1,
-   "id": "b7a5944e-0632-4095-a0c0-90f44d2ae4e8",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from ismn.interface import ISMN_Interface\n",
-    "import shutil\n",
-    "import tempfile"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "56959fc5-fa29-4ba5-b793-d32797a1a2c2",
    "metadata": {},
    "source": [
-    "Here we show how the use the custom metadata reader class to add additional variables to the python metadata stored with the ismn time series."
+    "Here we show how the use the custom metadata reader class to add additional variables to the python metadata stored with the ISMN time series."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "d31974ce-35ce-4a2d-a5c7-1f78d63b48e7",
    "metadata": {},
    "source": [
-    "# Data setup\n",
+    "## Data setup\n",
     "Here we use one of the testdata samples provided in this package (stored in the `test_data` folder).\n",
     "This archive contains 2 sensors at 2 stations in the `COSMOS` network and 2 sensors at the `fraye` station of the `FR_Aqui` network.\n",
-    "The goal is to add assign an additional metadata variable to the sensors at the 'fray' station. The data is taken from the VODCA archive (https://zenodo.org/record/2575599) and describes vegetation density on Jan 1st 2010. We store the value in a csv file (`vod.csv`) structured like this (normally we would add a line for as many ISMN stations as possible):\n",
+    "The goal is to assign an additional metadata variable to the sensors at the 'fray' station. The data is taken from the VODCA archive (https://zenodo.org/record/2575599) and describes vegetation density on Jan 1st 2010. We store the value in a `csv` file (`vod.csv` in the same directory as this notebook) structured like this (in our example only for one station, but normally we would add a line for as many ISMN stations as possible):\n",
     "\n",
     "```\n",
     "network;station;vod_k;vod_x\n",
     "FR_Aqui;fraye;0.64922965;0.39021793\n",
     "```\n",
     "\n",
-    "# Define custom metadata reader\n",
+    "## Set metadata reader\n",
     "\n",
-    "Then we set up the metadata reader. Here we use one of the predefined readers, but you can also write your own one as long as it inherits from the abstract class `ismn.custom.CustomMetaReader` and implements a function `read_metadata` which uses the information from the csv file to compare it to the previously loaded metadata for a station to find the matching entries, and either returns a `ismn.meta.MetaData` object or a dictionary of metadata variables and the according values."
+    "Then we set up the metadata reader. Here we use one of the predefined readers, but you can (and usually have to) also write your own reader as long as it inherits from the abstract class `ismn.custom.CustomMetaReader` and implements a function `read_metadata` which uses the information from previously loaded metadata for a station to find the matching entries in the provided data, and either returns a `ismn.meta.MetaData` object or a dictionary of metadata variables and the according values. Normally you use either the station latitude, longitude and sometimes also the sensor depth information; maybe even the station name."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 2,
+   "id": "b7a5944e-0632-4095-a0c0-90f44d2ae4e8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ismn.interface import ISMN_Interface\n",
+    "import shutil\n",
+    "import tempfile\n",
+    "from ismn.custom import CustomStationMetadataCsv"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
    "id": "ddf2b498-8601-4f89-9d37-51eba7a12efc",
    "metadata": {},
    "outputs": [],
    "source": [
-    "from ismn.custom import CustomStationMetadataCsv\n",
-    "\n",
     "my_meta_reader = CustomStationMetadataCsv('vod.csv')"
    ]
   },
@@ -72,7 +69,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 4,
    "id": "eb5786c4-c0f9-49de-990a-5db18793f987",
    "metadata": {},
    "outputs": [
@@ -89,16 +86,16 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "Files Processed: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 3/3 [00:00<00:00, 14.99it/s]"
+      "Files Processed: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 3/3 [00:00<00:00,  4.97it/s]"
      ]
     },
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
       "Metadata generation finished after 0 Seconds.\n",
-      "Metadata and Log stored in /tmp/tmp0tz6gsl5\n",
-      "Found existing ismn metadata in /tmp/tmp0tz6gsl5/Data_seperate_files_20170810_20180809.csv.\n"
+      "Metadata and Log stored in /tmp/tmp8omp4vpr\n",
+      "Found existing ismn metadata in /tmp/tmp8omp4vpr/Data_seperate_files_20170810_20180809.csv.\n"
      ]
     },
     {
@@ -115,18 +112,16 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "ddc0fca9-3bf2-4cf7-83db-133d297d8e32",
+   "cell_type": "markdown",
+   "id": "4222cfed-69f1-4cae-8c06-10a7f876853b",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "The values are new found in the metadata for the 'fraye' station"
+    "The newly added values are now found in the metadata for the 'fraye' station."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 5,
    "id": "7f293998-a3f0-4ac2-a673-d55e03229f3f",
    "metadata": {},
    "outputs": [
@@ -139,7 +134,7 @@
        "])"
       ]
      },
-     "execution_count": 7,
+     "execution_count": 5,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -153,7 +148,7 @@
    "id": "2a7bbf34-ffd4-42cd-832d-9c3fe473ae06",
    "metadata": {},
    "source": [
-    "But not in other stations"
+    "But not for other stations (in this case pandas automatically assigns NaN to the variable)."
    ]
   },
   {

diff --git a/docs/examples/index.rst b/docs/examples/index.rst
@@ -5,6 +5,7 @@ Examples
    :maxdepth: 1
 
    interface
+   custom_meta
 
 All shown examples are also available as ipython notebooks in ``ismn/docs/examples``.
-Data used in the examples is NOT provided here, and must be downloaded from `ISMN <https://ismn.earth/en/>`_.
+Data used in the examples is NOT provided here, and must be downloaded from `ISMN <https://ismn.earth/en/>`_.
diff --git a/environment.yml b/environment.yml
@@ -14,8 +14,8 @@ dependencies:
      - configparser
      - tqdm
      - more_itertools
-     - sphinx==4.0.3  # there seems to be an issue with 4.1.0 and nbsphinx, when this is resolved this line can be deleted to use the latest version.
+     - sphinx
      - nbsphinx
      - sphinx_rtd_theme
      - pytest
-     - pytest-cov
+     - pytest-cov