Implement filtering by variable depth

docs/api/filtering.rst

@@ -23,8 +23,9 @@ Timeseries data coordinates
 - Any *column* of the :attr:`IamDataFrame.coordinates <pyam.IamDataFrame.coordinates>`
   ('**region**', '**variable**', '**unit**'): string or list of strings
 - '**measurand**': a tuple (or list of tuples) of '*variable*' and '*unit*'
-- '**level**': the "depth" of entries in the '*variable*' column (number of '|')
-  (excluding the strings in the '*variable*' argument, if given)
+- '**depth**': the "depth" of entries in the '*variable*' column (number of '|')
+- '**level**': the "depth" of entries in the '*variable*' column (number of '|'),
+  excluding the strings in the '*variable*' argument (if given)
 - '**year**': takes an integer (int/:class:`numpy.int64`), a list of integers or
   a range. Note that the last year of a range is not included,
   so ``range(2010, 2015)`` is interpreted as ``[2010, ..., 2014]``

pyam/core.py

@@ -1905,7 +1905,7 @@ def filter(self, *, keep=True, inplace=False, **kwargs):
         if not inplace:
             return ret
 
-    def _apply_filters(self, level=None, **filters):  # noqa: C901
+    def _apply_filters(self, level=None, depth=None, **filters):  # noqa: C901
         """Determine rows to keep in data for given set of filters
 
         Parameters
@@ -1918,6 +1918,9 @@ def _apply_filters(self, level=None, **filters):  # noqa: C901
         regexp = filters.pop("regexp", False)
         keep = np.ones(len(self), dtype=bool)
 
+        if level is not None and depth is not None:
+            raise ValueError("Filter by `level` and `depth` not supported")
+
         if "variable" in filters and "measurand" in filters:
             raise ValueError("Filter by `variable` and `measurand` not supported")
 
@@ -2003,10 +2006,13 @@ def _apply_filters(self, level=None, **filters):  # noqa: C901
             keep = np.logical_and(keep, keep_col)
 
         if level is not None and not ("variable" in filters or "measurand" in filters):
-            # if level and variable/measurand is given, level-filter is applied there
+            # if level is given without variable/measurand, it is equivalent to depth
+            depth = level
+
+        if depth is not None:
             col = "variable"
             lvl_index, lvl_codes = get_index_levels_codes(self._data, col)
-            matches = find_depth(lvl_index, level=level)
+            matches = find_depth(lvl_index, level=depth)
             keep_col = get_keep_col(lvl_codes, matches)
 
             keep = np.logical_and(keep, keep_col)

tests/test_core.py

@@ -431,22 +431,46 @@ def test_filter_empty_df():
     assert len(obs) == 0
 
 
-def test_variable_and_measurand_raises(test_df):
-    pytest.raises(ValueError, test_df.filter, variable="foo", measurand=("foo", "bar"))
+def test_filter_variable_and_measurand_raises(test_df):
+    with pytest.raises(ValueError, match="Filter by `variable` and `measurand` not"):
+        test_df.filter(variable="foo", measurand=("foo", "bar"))
+
+
+def test_filter_level_and_depth_raises(test_df):
+    with pytest.raises(ValueError, match="Filter by `level` and `depth` not"):
+        test_df.filter(level=1, depth=2)
 
 
 @pytest.mark.parametrize(
     "filter_args",
     (dict(variable="*rimary*C*"), dict(measurand=("*rimary*C*", "EJ/*"))),
 )
-def test_filter_variable_and_depth(test_df, filter_args):
+def test_filter_variable_and_level(test_df, filter_args):
     obs = test_df.filter(**filter_args, level=0).variable
     assert obs == ["Primary Energy|Coal"]
 
+    obs = test_df.filter(**filter_args, level="0+").variable
+    assert obs == ["Primary Energy|Coal"]
+
     obs = test_df.filter(**filter_args, level=1).variable
     assert obs == []
 
 
+@pytest.mark.parametrize(
+    "filter_args",
+    (dict(variable="*rimary*C*"), dict(measurand=("*rimary*C*", "EJ/*"))),
+)
+def test_filter_variable_and_depth(test_df, filter_args):
+    obs = test_df.filter(**filter_args, depth=1).variable
+    assert obs == ["Primary Energy|Coal"]
+
+    obs = test_df.filter(**filter_args, depth="0+").variable
+    assert obs == ["Primary Energy|Coal"]
+
+    obs = test_df.filter(**filter_args, depth=0).variable
+    assert obs == []
+
+
 def test_filter_measurand_list(test_df):
     data = test_df.data
     data.loc[4, "variable"] = "foo"
@@ -460,18 +484,30 @@ def test_filter_measurand_list(test_df):
     assert obs.scenario == ["scen_b"]
 
 
-def test_variable_depth_0_keep_false(test_df):
-    obs = test_df.filter(level=0, keep=False).variable
+@pytest.mark.parametrize(
+    "filter_name",
+    ("level", "depth"),
+)
+def test_variable_depth_0_keep_false(test_df, filter_name):
+    obs = test_df.filter(**{filter_name: 0}, keep=False).variable
     assert obs == ["Primary Energy|Coal"]
 
 
-def test_variable_depth_raises(test_df):
-    pytest.raises(ValueError, test_df.filter, level="1/")
+@pytest.mark.parametrize(
+    "filter_name",
+    ("level", "depth"),
+)
+def test_variable_depth_raises(test_df, filter_name):
+    pytest.raises(ValueError, test_df.filter, **{filter_name: "1/"})
 
 
-def test_variable_depth_with_list_raises(test_df):
-    pytest.raises(ValueError, test_df.filter, level=["1", "2"])
-    pytest.raises(ValueError, test_df.filter, level=[1, 2])
+@pytest.mark.parametrize(
+    "filter_name",
+    ("level", "depth"),
+)
+def test_variable_depth_with_list_raises(test_df, filter_name):
+    pytest.raises(ValueError, test_df.filter, **{filter_name: ["1", "2"]})
+    pytest.raises(ValueError, test_df.filter, **{filter_name: [1, 2]})
 
 
 def test_timeseries(test_df):