From cd5191aa177cfb6c29da4eb89be8b88422f5e89e Mon Sep 17 00:00:00 2001
From: thorbjoernl <51087536+thorbjoernl@users.noreply.github.com>
Date: Fri, 10 Jan 2025 09:48:59 +0100
Subject: [PATCH 1/3] docs: topo_file->topo + mention support for dataset
 folders

---
 src/pyaro/timeseries/Filter.py | 39 ++++++++++++++++++++++++++++------
 1 file changed, 33 insertions(+), 6 deletions(-)

diff --git a/src/pyaro/timeseries/Filter.py b/src/pyaro/timeseries/Filter.py
index 67a4ed6..84c7bcf 100644
--- a/src/pyaro/timeseries/Filter.py
+++ b/src/pyaro/timeseries/Filter.py
@@ -1208,21 +1208,48 @@ def filter_stations(self, stations: dict[str, Station]) -> dict[str, Station]:
 @registered_filter
 class ValleyFloorRelativeAltitudeFilter(StationFilter):
     """
-    :param topo_file: Topography file path. Must be a dataset openable by xarray, with latitude
-        and longitude stored as "lat" and "lon" respectively. The variable that contains elevation
-        data is assumed to be in meters.
+    :param topo: Topography file path (either a file or a directory). Must be a dataset openable by
+        xarray, with latitude and longitude stored as "lat" and "lon" respectively. The variable
+        that contains elevation data is assumed to be in meters. If top is a directory, a
+        metadata.json file containing the geographic bounds of each file must be present (see below
+        for example).
     :param radius: Radius (in meters)
     :param topo_var: Variable name to use in topography dataset
     :param lower: Optional lower bound needed for relative altitude for station to be kept (in meters)
     :param upper: Optional upper bound needed for relative altitude for station to be kept (in meters)
-    :raises ModuleNotFoundError: If necessary optional dependencies are not available.
+    :raises ModuleNotFoundError: If necessary required additional dependencies (cf_units, xarray) are
+        not available.
 
     Note
     ----
     This implementation is only tested with GTOPO30 dataset to far.
 
-    Available versions can be found here:
-    /lustre/storeB/project/aerocom/aerocom1/AEROCOM_OBSDATA/GTOPO30/
+    Available versions of gtopo30 can be found here:
+    `/lustre/storeB/project/aerocom/aerocom1/AEROCOM_OBSDATA/GTOPO30/`
+
+    Note
+    ----
+    metadata.json should contain a mapping from each nc file, to it's geographic latitude/longitude
+    bounds.
+
+    For example:
+
+    ```
+    {
+        "N.nc": {
+            "w": -180,
+            "e": 180,
+            "n": 90,
+            "s": -10
+        },
+        "S.nc": {
+            "w": -180,
+            "e": 180,
+            "n": -10,
+            "s": -90
+        }
+    }
+    ```
     """
 
     def __init__(

From a5026a1df8a47309b1c723d5b243d7ff7fb7d344 Mon Sep 17 00:00:00 2001
From: thorbjoernl <51087536+thorbjoernl@users.noreply.github.com>
Date: Fri, 10 Jan 2025 09:53:18 +0100
Subject: [PATCH 2/3] Typo

---
 src/pyaro/timeseries/Filter.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pyaro/timeseries/Filter.py b/src/pyaro/timeseries/Filter.py
index 84c7bcf..99ff94b 100644
--- a/src/pyaro/timeseries/Filter.py
+++ b/src/pyaro/timeseries/Filter.py
@@ -1210,7 +1210,7 @@ class ValleyFloorRelativeAltitudeFilter(StationFilter):
     """
     :param topo: Topography file path (either a file or a directory). Must be a dataset openable by
         xarray, with latitude and longitude stored as "lat" and "lon" respectively. The variable
-        that contains elevation data is assumed to be in meters. If top is a directory, a
+        that contains elevation data is assumed to be in meters. If `topo` is a directory, a
         metadata.json file containing the geographic bounds of each file must be present (see below
         for example).
     :param radius: Radius (in meters)

From 2c9ab9183694b4e79dfd605b15f44273314d2e92 Mon Sep 17 00:00:00 2001
From: thorbjoernl <51087536+thorbjoernl@users.noreply.github.com>
Date: Fri, 10 Jan 2025 13:00:42 +0100
Subject: [PATCH 3/3] docs: Add general description of vfloor filter

---
 src/pyaro/timeseries/Filter.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/pyaro/timeseries/Filter.py b/src/pyaro/timeseries/Filter.py
index 99ff94b..4058e05 100644
--- a/src/pyaro/timeseries/Filter.py
+++ b/src/pyaro/timeseries/Filter.py
@@ -1208,6 +1208,12 @@ def filter_stations(self, stations: dict[str, Station]) -> dict[str, Station]:
 @registered_filter
 class ValleyFloorRelativeAltitudeFilter(StationFilter):
     """
+    Filter for filtering stations based on the difference between the station altitude and valley
+    floor altitude (defined as the lowest altitude within a radius around the station). This ensures
+    that plateau sites are treated like "surface" sites, while sites in hilly or mountaineous areas
+    (eg. Schauinsland) are considered mountain sites. This approach has been used by several papers
+    (eg. Fowler et al., Lloibl et al. 1994).
+
     :param topo: Topography file path (either a file or a directory). Must be a dataset openable by
         xarray, with latitude and longitude stored as "lat" and "lon" respectively. The variable
         that contains elevation data is assumed to be in meters. If `topo` is a directory, a