Release candidate 2.2 (#839)

AUTHORS.rst

@@ -20,9 +20,9 @@ The following persons contributed to the development of the |pyam| package:
 - Florian Maczek `@macflo8 <https://github.com/macflo8>`_
 - Laura Wienpahl `@LauWien <https://github.com/LauWien>`_
 - Philip Hackstock `@phackstock <https://github.com/phackstock>`_
-- Pietro Monticone `@pitmonticone <https://github.com/pitmonticone>`
-- Edward Byers `@byersiiasa <https://github.com/byersiiasa>`
-- Fridolin Glatter `@glatterf42 <https://github.com/glatterf42>`
+- Pietro Monticone `@pitmonticone <https://github.com/pitmonticone>`_
+- Edward Byers `@byersiiasa <https://github.com/byersiiasa>`_
+- Fridolin Glatter `@glatterf42 <https://github.com/glatterf42>`_
 
 | The core maintenance of the |pyam| package is done by
   the *Scenario Services & Scientific Software* research theme

RELEASE_NOTES.md

@@ -1,4 +1,10 @@
-# Next release
+# Release v2.1.0
+
+## Highlights
+
+- Direct integration with **ixmp4** platforms hosted by IIASA
+- More flexible and intuitive signature for data validation and categorization
+- Support for Python 3.12 and migrate to poetry & ruff
 
 ## Dependency changes
 

docs/.gitignore

@@ -3,6 +3,7 @@ _build
 build
 
 # exclude built gallery folder (built by sphinx-gallery module)
+sg_execution_times.rst
 gallery
 modules
 

docs/api.rst

@@ -23,15 +23,6 @@ and methods.
    api/timeseries
    api/variables
 
-Logging behaviour in Jupyter notebooks
---------------------------------------
-
-The |pyam| package wants to provide sensible defaults for users unfamiliar with setting
-up python's logging library (`read more`_), and therefore will add a streamhandler if
-(and only if) it determines to be running within a notebook.
-
-.. _`read more` : https://realpython.com/python-logging/#basic-configurations
-
 Intersphinx mapping
 -------------------
 

pyam/core.py

@@ -91,8 +91,8 @@ class IamDataFrame(object):
         or long (key/value columns) format.
         The dataframe will be downselected to scenarios present in `data`.
     index : list, optional
-        Columns to use for resulting IamDataFrame index.
-    kwargs
+        Columns to use as :attr:`index <IamDataFrame.index>` names.
+    **kwargs
         If `value=<col>`, melt column `<col>` to 'value' and use `<col>` name
         as 'variable'; or mapping of required columns (:code:`IAMC_IDX`) to
         any of the following:
@@ -103,8 +103,7 @@ class IamDataFrame(object):
 
     Notes
     -----
-    A :class:`pandas.DataFrame` can have the required dimensions
-    as columns or index.
+    A :class:`pandas.DataFrame` can have the required dimensions as columns or index.
     R-style integer column headers (i.e., `X2015`) are acceptable.
 
     When initializing an :class:`IamDataFrame` from an xlsx file,
@@ -307,8 +306,8 @@ def print_meta_row(m, t, lst):
                 [
                     print_meta_row(m, t, self.meta[m].unique())
                     for m, t in zip(
-                        self.meta.columns[0:meta_rows], self.meta.dtypes[0:meta_rows]
-                    )
+                    self.meta.columns[0:meta_rows], self.meta.dtypes[0:meta_rows]
+                )
                 ]
             )
             # print `...` if more than `meta_rows` columns
@@ -341,8 +340,7 @@ def _execute_run_control(self):
     def index(self):
         """Return all model-scenario combinations as :class:`pandas.MultiIndex`
 
-        The index allows to loop over the available model-scenario combinations
-        using:
+        The index allows to loop over all model-scenario combinations using:
 
         .. code-block:: python
 
@@ -403,7 +401,7 @@ def list_or_str(x):
 
     @property
     def time(self):
-        """The time index, i.e., axis labels related to the time domain.
+        """The time index, i.e., axis labels related to the time domain
 
         Returns
         -------
@@ -514,8 +512,8 @@ def equals(self, other):
 
         Parameters
         ----------
-        other : IamDataFrame
-            the other :class:`IamDataFrame` to be compared with `self`
+        other : :class:`IamDataFrame`
+            The other :class:`IamDataFrame` to be compared with `self`
         """
         if not isinstance(other, IamDataFrame):
             raise ValueError("`other` is not an `IamDataFrame` instance")
@@ -545,22 +543,22 @@ def append(
 
         Parameters
         ----------
-        other : IamDataFrame, pandas.DataFrame or data file
-            Any object castable as IamDataFrame to be appended
+        other : :class:`IamDataFrame`, :class:`pandas.DataFrame` or file-like
+            Any object castable as :class:`IamDataFrame` to be appended
         ignore_meta_conflict : bool, optional
-            If False and `other` is an IamDataFrame, raise an error if
+            If False and `other` is an :class:`IamDataFrame`, raise an error if
             any meta columns present in `self` and `other` are not identical.
         inplace : bool, optional
             If True, do operation inplace and return None
         verify_integrity : bool, optional
             If True, verify integrity of index
-        kwargs
+        **kwargs
             Passed to :class:`IamDataFrame(other, **kwargs) <IamDataFrame>`
             if `other` is not already an IamDataFrame
 
         Returns
         -------
-        IamDataFrame
+        :class:`IamDataFrame`
             If *inplace* is :obj:`False`.
         None
             If *inplace* is :obj:`True`.
@@ -671,7 +669,7 @@ def interpolate(self, time, inplace=False, **kwargs):
              This must match the datetime/year format of `self`.
         inplace : bool, optional
             if True, do operation inplace and return None
-        kwargs
+        **kwargs
             passed to :meth:`pandas.DataFrame.interpolate`
         """
         ret = self.copy() if not inplace else self
@@ -909,7 +907,7 @@ def set_meta_from_data(self, name, method=None, column="value", **kwargs):
             required if downselected data do not yield unique values
         column : str, optional
             the column from `data` to be used to derive the indicator
-        kwargs
+        **kwargs
             passed to :meth:`filter` for downselected data
         """
         _data = self.filter(**kwargs).data
@@ -937,20 +935,20 @@ def categorize(
         Parameters
         ----------
         name : str
-            Name of the meta indicator
+            Name of the meta indicator.
         value : str
-            Value of the meta indicator
+            Value of the meta indicator.
         criteria : dict, optional, deprecated
            This option is deprecated; dictionary with variable keys and validation
            mappings ('up' and 'lo' for respective bounds, 'year' for years).
         upper_bound, lower_bound : float, optional
             Upper and lower bounds for validation criteria of timeseries :attr:`data`.
         color : str, optional
-            Assign a color to this category for plotting
+            Assign a color to this category for plotting.
         marker : str, optional
-            Assign a marker to this category for plotting
+            Assign a marker to this category for plotting.
         linestyle : str, optional
-            Assign a linestyle to this category for plotting
+            Assign a linestyle to this category for plotting.
         **kwargs
             Passed to :meth:`slice` to downselect datapoints for validation.
 
@@ -1067,7 +1065,7 @@ def require_data(
             return missing_required.to_frame(index=False)
 
     def require_variable(self, *args, **kwargs):
-        """This method is deprecated, use `df.require_data()` instead."""
+        """This method is deprecated, use :meth:`IamDataFrame.require_data()`."""
         # TODO: deprecated, remove for release >= 3.0
         raise DeprecationWarning("Use `df.require_data()` instead.")
 
@@ -1319,7 +1317,7 @@ def normalize(self, inplace=False, **kwargs):
         ----------
         inplace : bool, optional
             if :obj:`True`, do operation inplace and return None
-        kwargs
+        **kwargs
             the column and value on which to normalize (e.g., `year=2005`)
         """
         if len(kwargs) > 1 or self.time_col not in kwargs:
@@ -1361,7 +1359,7 @@ def offset(self, padding=0, fill_value=None, inplace=False, **kwargs):
             https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.subtract.html
         inplace : bool, optional
             if :obj:`True`, do operation inplace and return None
-        kwargs
+        **kwargs
             the column and value on which to offset (e.g., `year=2005`)
         """
         if len(kwargs) > 1 or self.time_col not in kwargs:
@@ -1461,7 +1459,7 @@ def check_aggregate(
             does not match the aggregated components.
         multiplier : number, optional
             Multiplicative factor when comparing variable and sum of components.
-        kwargs : Tolerance arguments for comparison of values
+        **kwargs : Tolerance arguments for comparison of values
             Passed to :func:`numpy.isclose`.
 
         Returns
@@ -1610,7 +1608,7 @@ def check_aggregate_region(
             does not match the aggregated components.
         drop_negative_weights : bool, optional
             Removes any aggregated values that are computed using negative weights
-        kwargs : Tolerance arguments for comparison of values
+        **kwargs : Tolerance arguments for comparison of values
             Passed to :func:`numpy.isclose`.
 
         Returns
@@ -1804,7 +1802,7 @@ def check_internal_consistency(self, components=False, **kwargs):
 
         Parameters
         ----------
-        kwargs : arguments for comparison of values
+        **kwargs : arguments for comparison of values
             passed to :func:`numpy.isclose`
         components : bool, optional
             passed to :meth:`check_aggregate_region` if `True`, use all
@@ -2267,7 +2265,7 @@ def divide(
         return self._finalize(_value, append=append)
 
     def apply(
-        self, func, name, axis="variable", fillna=None, append=False, args=(), **kwds
+        self, func, name, axis="variable", fillna=None, append=False, args=(), **kwargs
     ):
         """Apply a function to components of timeseries data along an `axis`
 
@@ -2291,7 +2289,7 @@ def apply(
             Whether to append aggregated timeseries data to this instance.
         args : tuple or list of str
             List of variables to pass as positional arguments to `func`.
-        **kwds
+        **kwargs
             Additional keyword arguments to pass as keyword arguments to `func`. If the
             name of a variable is given, the associated timeseries is passed. Otherwise
             the value itself is passed.
@@ -2316,10 +2314,11 @@ def apply(
         As a result, the notation of returned units may differ from the input format.
         For example, the unit :code:`EJ/yr` may be reformatted to :code:`EJ / a`.
         """
-        _value = _op_data(self, name, func, axis=axis, fillna=fillna, args=args, **kwds)
 
-        # append to `self` or return as `IamDataFrame`
-        return self._finalize(_value, append=append)
+        return self._finalize(
+            _op_data(self, name, func, axis=axis, fillna=fillna, args=args, **kwargs),
+            append=append,
+        )
 
     def diff(self, mapping, periods=1, append=False):
         """Compute the difference of timeseries data along the time dimension
@@ -2522,7 +2521,7 @@ def load_meta(self, path, sheet_name="meta", ignore_conflict=False, **kwargs):
         ignore_conflict : bool, optional
             If `True`, values in `path` take precedence over existing `meta`.
             If `False`, raise an error in case of conflicts.
-        kwargs
+        **kwargs
             Passed to :func:`pandas.read_excel` or :func:`pandas.read_csv`
         """
 
@@ -2589,7 +2588,7 @@ def _empty_iamframe(index):
 
 
 def validate(df, criteria={}, exclude_on_fail=False, **kwargs):
-    """This method is deprecated, use `df.validate()` instead."""
+    """This method is deprecated, use :meth:`IamDataFrame.validate()` instead."""
     # TODO: method is deprecated, remove for release >= 3.0
     deprecation_warning("Use `IamDataFrame.validate()` instead.")
     fdf = df.filter(**kwargs)
@@ -2600,15 +2599,15 @@ def validate(df, criteria={}, exclude_on_fail=False, **kwargs):
 
 
 def require_variable(*args, **kwargs):
-    """This method is deprecated, use `df.require_data()` instead."""
+    """This method is deprecated, use :meth:`IamDataFrame.require_data()` instead."""
     # TODO: deprecated, remove for release >= 3.0
-    raise DeprecationWarning("Use `df.require_data()` instead.")
+    raise DeprecationWarning("Use `IamDataFrame.require_data()` instead.")
 
 
 def categorize(
     df, name, value, criteria, color=None, marker=None, linestyle=None, **kwargs
 ):
-    """This method is deprecated, use `df.validate()` instead."""
+    """This method is deprecated, use :meth:`IamDataFrame.categorize()` instead."""
     # TODO: method is deprecated, remove for release >= 3.0
     deprecation_warning("Use `IamDataFrame.categorize()` instead.")
     fdf = df.filter(**kwargs)
@@ -2636,9 +2635,8 @@ def check_aggregate(
     Parameters
     ----------
     df : IamDataFrame
-    args : passed to :meth:`IamDataFrame.check_aggregate`
-    kwargs : used for downselecting IamDataFrame
-        passed to :meth:`IamDataFrame.filter`
+    **kwargs
+        Passed to :meth:`IamDataFrame.filter`
     """
     fdf = df.filter(**kwargs)
     if len(fdf.data) > 0:
@@ -2664,7 +2662,7 @@ def filter_by_meta(data, df, join_meta=False, **kwargs):
         IamDataFrame from which meta columns are filtered and joined (optional)
     join_meta : bool, optional
         join selected columns from `df.meta` on `data`
-    kwargs
+    **kwargs
         Meta columns to be filtered/joined, where `col=...` applies filters
         with the given arguments (using :meth:`utils.pattern_match`).
         Using `col=None` joins the column without filtering (setting col
@@ -2714,15 +2712,17 @@ def compare(
     Parameters
     ----------
     left, right : IamDataFrames
-        two :class:`IamDataFrame` instances to be compared
+        Two :class:`IamDataFrame` instances to be compared
     left_label, right_label : str, optional
-        column names of the returned :class:`pandas.DataFrame`
+        Column names of the returned :class:`pandas.DataFrame`
     drop_close : bool, optional
-        remove all data where `left` and `right` are close
-    kwargs : arguments for comparison of values
-        passed to :func:`numpy.isclose`
+        Remove all data where `left` and `right` are close
+    **kwargs : arguments for comparison of values
+        Passed to :func:`numpy.isclose`
     """
-    return _compare(left, right, left_label, right_label, drop_close=True, **kwargs)
+    return _compare(
+        left, right, left_label, right_label, drop_close=drop_close, **kwargs
+    )
 
 
 def concat(objs, ignore_meta_conflict=False, **kwargs):  # noqa: C901
@@ -2735,7 +2735,7 @@ def concat(objs, ignore_meta_conflict=False, **kwargs):  # noqa: C901
     ignore_meta_conflict : bool, optional
         If False, raise an error if any meta columns present in `dfs` are not identical.
         If True, values in earlier elements of `dfs` take precedence.
-    kwargs
+    **kwargs
         Passed to :class:`IamDataFrame(other, **kwargs) <IamDataFrame>`
         for any item of `dfs` which isn't already an IamDataFrame.
 

pyam/iiasa.py

@@ -295,7 +295,7 @@ def index(self, default_only=True, **kwargs):
         default_only : bool, optional
             If `True`, return *only* the default version of a model/scenario.
             If `False`, return all versions.
-        kwargs
+        **kwargs
             Arguments to filter by *model* and *scenario*, `*` can be used as wildcard.
         """
         if "default" in kwargs:
@@ -316,7 +316,7 @@ def meta(self, default_only=True, run_id=False, **kwargs):
             If `False`, return all versions.
         run_id : bool, optional
             Include "run id" column
-        kwargs
+        **kwargs
             Arguments to filer by *model* and *scenario*, `*` can be used as wildcard
         """
         if "default" in kwargs:
@@ -347,7 +347,7 @@ def properties(self, default_only=True, **kwargs):
         default_only : bool, optional
             If `True`, return *only* the default version of a model/scenario.
             If `False`, return all versions.
-        kwargs
+        **kwargs
             Arguments to filer by *model* and *scenario*, `*` can be used as wildcard
         """
         if "default" in kwargs:
@@ -488,7 +488,7 @@ def query(self, default_only=True, meta=True, **kwargs):
         meta : bool or list, optional
             If :obj:`True`, merge all meta columns indicators
             (or subset if list is given).
-        kwargs
+        **kwargs
             Available keyword arguments include
 
             - model