BaseObject and rework of tags system, including dynamic tags

sktime/base/__init__.py

@@ -2,11 +2,14 @@
 # -*- coding: utf-8 -*-
 # copyright: sktime developers, BSD-3-Clause License (see LICENSE file)
 
-__author__ = ["Markus Löning"]
+"""Base classes for defining estimators and other objects in sktime."""
+
+__author__ = ["mloning", "RNKuhns", "fkiraly"]
 __all__ = [
+    "BaseObject",
     "BaseEstimator",
     "_HeterogenousMetaEstimator",
 ]
 
-from sktime.base._base import BaseEstimator
+from sktime.base._base import BaseObject, BaseEstimator
 from sktime.base._meta import _HeterogenousMetaEstimator

sktime/base/_base.py

@@ -1,9 +1,49 @@
-#!/usr/bin/env python3 -u
 # -*- coding: utf-8 -*-
-# copyright: sktime developers, BSD-3-Clause License (see LICENSE file)
+"""
+Base class template for objects and fittable objects.
 
-__author__ = ["Markus Löning"]
-__all__ = ["BaseEstimator"]
+templates in this module:
+
+    BaseObject - object with parameters and tags
+    BaseEstimator - BaseObject that can be fitted
+
+Interface specifications below.
+
+---
+
+    class name: BaseObject
+
+Hyper-parameter inspection and setter methods:
+    inspect hyper-parameters    - get_params()
+    setting hyper-parameters    - set_params(**params)
+
+Tag inspection and setter methods
+    inspect tags (all)          - get_tags()
+    inspect tags (one tag)      - get_tag(tag_name: str, tag_value_default=None)
+    inspect tags (class only)   - get_class_tags()
+    inspect tags (class, one)   - get_class_tag(tag_name:str, tag_value_default=None)
+    setting dynamic tags        - set_tag(**tag_dict: dict)
+    set mirrored dynamic tags   - mirror_tags(estimator)
+
+---
+
+    class name: BaseEstimator
+
+Provides all interface points of BaseObject, plus:
+
+Parameter inspection:
+    fitted parameter inspection - get_fitted_params()
+
+State:
+    fitted model/strategy   - by convention, any attributes ending in "_"
+    fitted state flag       - is_fitted (property)
+    fitted state check      - check_is_fitted (raises error if not is_fitted)
+
+copyright: sktime developers, BSD-3-Clause License (see LICENSE file)
+"""
+
+__author__ = ["mloning", "RNKuhns", "fkiraly"]
+__all__ = ["BaseEstimator", "BaseObject"]
 
 import inspect
 
@@ -14,14 +54,160 @@
 from sktime.exceptions import NotFittedError
 
 
-class BaseEstimator(_BaseEstimator):
+class BaseObject(_BaseEstimator):
+    """Base class for parametric objects with tags sktime.
+
+    Extends scikit-learn's BaseEstimator to include sktime interface for tags.
+    """
+
+    def __init__(self):
+        self._tags_dynamic = dict()
+        super(BaseObject, self).__init__()
+
+    @classmethod
+    def get_class_tags(cls):
+        """Get class tags from estimator class and all its parent classes.
+
+        Returns
+        -------
+        collected_tags : dictionary of tag names : tag values
+            collected from _tags class attribute via nested inheritance
+            NOT overridden by dynamic tags set by set_tags or mirror_tags
+        """
+        collected_tags = dict()
+
+        # We exclude the last two parent classes: sklearn.base.BaseEstimator and
+        # the basic Python object.
+        for parent_class in reversed(inspect.getmro(cls)[:-2]):
+            if hasattr(parent_class, "_tags"):
+                # Need the if here because mixins might not have _more_tags
+                # but might do redundant work in estimators
+                # (i.e. calling more tags on BaseEstimator multiple times)
+                more_tags = parent_class._tags
+                collected_tags.update(more_tags)
+
+        return collected_tags
+
+    @classmethod
+    def get_class_tag(cls, tag_name, tag_value_default=None):
+        """Get tag value from estimator class (only class tags).
+
+        Arguments
+        ---------
+        tag_name : str, name of tag value
+        tag_value_default : any type, default/fallback value if tag is not found
+
+        Returns
+        -------
+        tag_value : value of the tag tag_name in self if found
+                    if tag is not found, returns tag_value_default
+        """
+        collected_tags = cls.get_class_tags()
+
+        if tag_name in collected_tags.keys():
+            return collected_tags[tag_name]
+        else:
+            return tag_value_default
+
+    def get_tags(self):
+        """Get tags from estimator class and dynamic tag overrides.
+
+        Returns
+        -------
+        collected_tags : dictionary of tag names : tag values
+            collected from _tags class attribute via nested inheritance
+            then any overrides and new tags from _tags_dynamic object attribute
+        """
+        collected_tags = type(self).get_class_tags().copy()
+
+        if hasattr(self, "_tags_dynamic"):
+            collected_tags.update(self._tags_dynamic)
+
+        return collected_tags
+
+    def get_tag(self, tag_name, tag_value_default=None):
+        """Get tag value from estimator class and dynamic tag overrides.
+
+        Arguments
+        ---------
+        tag_name : str, name of tag value
+        tag_value_default : any type, default/fallback value if tag is not found
+
+        Returns
+        -------
+        tag_value : value of the tag tag_name in self if found
+                    if tag is not found, returns tag_value_default
+        """
+        collected_tags = self.get_tags()
+
+        if tag_name in collected_tags.keys():
+            return collected_tags[tag_name]
+        else:
+            return tag_value_default
+
+    def set_tags(self, **tag_dict):
+        """Set dynamic tags to given values.
+
+        Arguments
+        ---------
+        tag_dict : dictionary of tag names : tag values
+
+        Returns
+        -------
+        reference to self
+
+        State change
+        ------------
+        sets tag values in tag_dict as dynamic tags in self
+        """
+        self._tags_dynamic.update(tag_dict.copy())
+
+        return self
+
+    def mirror_tags(self, estimator, tag_set=None):
+        """Mirror tags from estimator as dynamic override.
+
+        Arguments
+        ---------
+        estimator : an estimator inheriting from BaseEstimator
+        tag_set : list of str, or str; tag names
+            default = list of all tags in estimator
+
+        Returns
+        -------
+        reference to self
+
+        State change
+        ------------
+        sets tag values in tag_set from estimator as dynamic tags in self
+        """
+        tags_est = estimator.get_tags().copy()
+
+        # if tag_set is not passed, default is all tags in estimator
+        if tag_set is None:
+            tag_set = tags_est.keys()
+        else:
+            # if tag_set is passed, intersect keys with tags in estimator
+            if not isinstance(tag_set, list):
+                tag_set = [tag_set]
+            tag_set = [key for key in tag_set if key in tags_est.keys()]
+
+        update_dict = {key: tags_est[key] for key in tag_set}
+
+        self.set_tags(update_dict)
+
+        return self
+
+
+class BaseEstimator(BaseObject):
     """Base class for defining estimators in sktime.
 
-    Extends scikit-learn's BaseEstimator.
+    Extends sktime's BaseObject to include basic functionality for fittable estimators.
     """
 
     def __init__(self):
         self._is_fitted = False
+        super(BaseEstimator, self).__init__()
 
     @property
     def is_fitted(self):
@@ -42,27 +228,6 @@ def check_is_fitted(self):
                 f"been fitted yet; please call `fit` first."
             )
 
-    @classmethod
-    def _all_tags(cls):
-        """Get tags from estimator class and all its parent classes."""
-        # We here create a separate estimator tag interface in addition to the one in
-        # scikit-learn to make sure we do not interfere with scikit-learn's one
-        # when we inherit from scikit-learn classes. We also make estimator tags a
-        # class rather than object attribute.
-        collected_tags = dict()
-
-        # We exclude the last two parent classes; sklearn.base.BaseEstimator and
-        # the basic Python object.
-        for parent_class in reversed(inspect.getmro(cls)[:-2]):
-            if hasattr(parent_class, "_tags"):
-                # Need the if here because mixins might not have _more_tags
-                # but might do redundant work in estimators
-                # (i.e. calling more tags on BaseEstimator multiple times)
-                more_tags = parent_class._tags
-                collected_tags.update(more_tags)
-
-        return collected_tags
-
 
 def _clone_estimator(base_estimator, random_state=None):
     estimator = clone(base_estimator)

sktime/base/_meta.py

@@ -11,16 +11,17 @@
 
 
 class _HeterogenousMetaEstimator(BaseEstimator, metaclass=ABCMeta):
-    """Handles parameter management for estimtators composed of named
-    estimators.
+    """Handles parameter management for estimtators composed of named estimators.
 
-    from sklearn utils.metaestimator.py
+    From sklearn utils.metaestimator.py
     """
 
     def get_params(self, deep=True):
+        """Return estimator parameters."""
         raise NotImplementedError("abstract method")
 
     def set_params(self, **params):
+        """Set estimator parameters."""
         raise NotImplementedError("abstract method")
 
     def _get_params(self, attr, deep=True):

sktime/classification/base.py

@@ -77,7 +77,7 @@ def fit(self, X, y):
         sets is_fitted flag to true
         """
 
-        coerce_to_numpy = self._all_tags()["coerce-X-to-numpy"]
+        coerce_to_numpy = self.get_class_tag("coerce-X-to-numpy", False)
 
         X, y = check_X_y(X, y, coerce_to_numpy=coerce_to_numpy)
 
@@ -103,7 +103,7 @@ def predict(self, X):
         y : array-like, shape =  [n_instances] - predicted class labels
         """
 
-        coerce_to_numpy = self._all_tags()["coerce-X-to-numpy"]
+        coerce_to_numpy = self.get_class_tag("coerce-X-to-numpy", False)
 
         X = check_X(X, coerce_to_numpy=coerce_to_numpy)
         self.check_is_fitted()

sktime/dists_kernels/compose_tab_to_panel.py

@@ -75,7 +75,7 @@ def _transform(self, X, X2=None):
             aggfunc = np.mean
             aggfunc_is_symm = True
 
-        transformer_symm = self.transformer._all_tags()["symmetric"]
+        transformer_symm = self.transformer.get_tag("symmetric", False)
 
         # whether we know that resulting matrix must be symmetric
         # a sufficient condition for this:

sktime/forecasting/base/_base.py

@@ -550,7 +550,7 @@ def _set_fh(self, fh):
         ----------
         fh : None, int, list, np.ndarray or ForecastingHorizon
         """
-        requires_fh = self._all_tags().get("requires-fh-in-fit", True)
+        requires_fh = self.get_tag("requires-fh-in-fit", True)
 
         msg = (
             f"This is because fitting of the `"

sktime/forecasting/compose/_pipeline.py

@@ -11,7 +11,6 @@
 from sktime.forecasting.base._base import BaseForecaster
 from sktime.forecasting.base._base import DEFAULT_ALPHA
 from sktime.transformations.base import _SeriesToSeriesTransformer
-from sktime.utils import _has_tag
 from sktime.utils.validation.series import check_series
 
 
@@ -354,7 +353,7 @@ def _predict(self, fh=None, X=None, return_pred_int=False, alpha=DEFAULT_ALPHA):
         for _, _, transformer in self._iter_transformers(reverse=True):
             # skip sktime transformers where inverse transform
             # is not wanted ur meaningful (e.g. Imputer, HampelFilter)
-            skip_trafo = transformer._all_tags().get("skip-inverse-transform", False)
+            skip_trafo = transformer.get_tag("skip-inverse-transform", False)
             if not skip_trafo:
                 y_pred = transformer.inverse_transform(y_pred)
         return y_pred
@@ -394,6 +393,6 @@ def inverse_transform(self, Z, X=None):
         self.check_is_fitted()
         zt = check_series(Z, enforce_univariate=True)
         for _, _, transformer in self._iter_transformers(reverse=True):
-            if not _has_tag(transformer, "skip-inverse-transform"):
+            if not transformer.get_tag("skip-inverse-transform", False):
                 zt = transformer.inverse_transform(zt, X)
         return zt

sktime/forecasting/tests/test_sktime_forecasters.py

@@ -73,10 +73,12 @@ def test_oh_setting(Forecaster):
 # check setting/getting API for forecasting horizon
 
 # divide Forecasters into groups based on when fh is required
-FORECASTERS_REQUIRED = [f for f in FORECASTERS if f._all_tags()["requires-fh-in-fit"]]
+FORECASTERS_REQUIRED = [
+    f for f in FORECASTERS if f.get_class_tag("requires-fh-in-fit", True)
+]
 
 FORECASTERS_OPTIONAL = [
-    f for f in FORECASTERS if not f._all_tags()["requires-fh-in-fit"]
+    f for f in FORECASTERS if not f.get_class_tag("requires-fh-in-fit", True)
 ]