***************************************** :py:mod:`wildboar.explain.counterfactual` ***************************************** .. py:module:: wildboar.explain.counterfactual .. autoapi-nested-parse:: Counterfactual explanations. The :mod:`wildboar.explain.counterfactual` module includes numerous methods for generating counterfactual explanations. .. !! processed by numpydoc !! Package Contents ---------------- Classes ------- .. autoapisummary:: wildboar.explain.counterfactual.KNeighborsCounterfactual wildboar.explain.counterfactual.PrototypeCounterfactual wildboar.explain.counterfactual.ShapeletForestCounterfactual Functions --------- .. autoapisummary:: wildboar.explain.counterfactual.counterfactuals wildboar.explain.counterfactual.proximity .. py:class:: KNeighborsCounterfactual(method='auto', random_state=None) Fit a counterfactual explainer to a k-nearest neighbors classifier. :Parameters: **method** : {"auto", "mean", "medoid"}, optional The method for generating counterfactuals. If 'auto', counterfactuals are generated using k-means if possible and k-medoids otherwise. If 'mean', counterfactuals are always generated using k-means, which fails if the estimator is fitted with a metric other than 'euclidean', 'dtw' or 'wdtw. If 'medoid', counterfactuals are generated using k-medoids. .. versionadded:: 1.2 **random_state** : int or RandomState, optional - If `int`, `random_state` is the seed used by the random number generator. - If `RandomState` instance, `random_state` is the random number generator. - If `None`, the random number generator is the `RandomState` instance used by `np.random`. .. rubric:: References Karlsson, I., Rebane, J., Papapetrou, P., & Gionis, A. (2020). Locally and globally explainable time series tweaking. Knowledge and Information Systems, 62(5), 1671-1700. .. only:: latex :Attributes: **explainer_** : dict The explainer for each label .. !! processed by numpydoc !! .. py:method:: fit_explain(estimator, x=None, y=None, **kwargs) Fit and return the explanation. :Parameters: **estimator** : Estimator The estimator to explain. **x** : time-series, optional The input time series. **y** : array-like of shape (n_samples, ), optional The labels. **\*\*kwargs** Optional extra arguments. :Returns: ndarray The explanation. .. !! processed by numpydoc !! .. py:method:: get_metadata_routing() Get metadata routing of this object. Please check :ref:`User Guide ` on how the routing mechanism works. :Returns: **routing** : MetadataRequest A :class:`~sklearn.utils.metadata_routing.MetadataRequest` encapsulating routing information. .. !! processed by numpydoc !! .. py:method:: get_params(deep=True) Get parameters for this estimator. :Parameters: **deep** : bool, default=True If True, will return the parameters for this estimator and contained subobjects that are estimators. :Returns: **params** : dict Parameter names mapped to their values. .. !! processed by numpydoc !! .. py:method:: plot(x=None, y=None, ax=None) Plot the explanation. :Returns: **ax** : Axes The axes object .. !! processed by numpydoc !! .. py:method:: score(x, y) Score the counterfactual explainer in terms of closeness of fit. :Parameters: **x** : array-like of shape (n_samples, n_timestep) The samples. **y** : array-like of shape (n_samples, ) The desired counterfactal label. :Returns: **score** : float The closensess of fit. .. !! processed by numpydoc !! .. py:method:: set_params(**params) Set the parameters of this estimator. The method works on simple estimators as well as on nested objects (such as :class:`~sklearn.pipeline.Pipeline`). The latter have parameters of the form ``__`` so that it's possible to update each component of a nested object. :Parameters: **\*\*params** : dict Estimator parameters. :Returns: **self** : estimator instance Estimator instance. .. !! processed by numpydoc !! .. py:class:: PrototypeCounterfactual(metric='euclidean', *, r=1.0, g=0.05, max_iter=100, step_size=0.1, n_prototypes='auto', target='predict', method='sample', min_shapelet_size=0.0, max_shapelet_size=1.0, random_state=None, verbose=False) Model agnostic approach for constructing counterfactual explanations. .. rubric:: References Samsten, Isak (2020). Model agnostic time series counterfactuals .. only:: latex :Attributes: **estimator_** : object The estimator for which counterfactuals are computed **classes_** : ndarray The classes **partitions_** : dict Dictionary of classes and PrototypeSampler **target_** : TargetEvaluator The target evaluator .. !! processed by numpydoc !! .. py:method:: fit_explain(estimator, x=None, y=None, **kwargs) Fit and return the explanation. :Parameters: **estimator** : Estimator The estimator to explain. **x** : time-series, optional The input time series. **y** : array-like of shape (n_samples, ), optional The labels. **\*\*kwargs** Optional extra arguments. :Returns: ndarray The explanation. .. !! processed by numpydoc !! .. py:method:: get_metadata_routing() Get metadata routing of this object. Please check :ref:`User Guide ` on how the routing mechanism works. :Returns: **routing** : MetadataRequest A :class:`~sklearn.utils.metadata_routing.MetadataRequest` encapsulating routing information. .. !! processed by numpydoc !! .. py:method:: get_params(deep=True) Get parameters for this estimator. :Parameters: **deep** : bool, default=True If True, will return the parameters for this estimator and contained subobjects that are estimators. :Returns: **params** : dict Parameter names mapped to their values. .. !! processed by numpydoc !! .. py:method:: plot(x=None, y=None, ax=None) Plot the explanation. :Returns: **ax** : Axes The axes object .. !! processed by numpydoc !! .. py:method:: score(x, y) Score the counterfactual explainer in terms of closeness of fit. :Parameters: **x** : array-like of shape (n_samples, n_timestep) The samples. **y** : array-like of shape (n_samples, ) The desired counterfactal label. :Returns: **score** : float The closensess of fit. .. !! processed by numpydoc !! .. py:method:: set_params(**params) Set the parameters of this estimator. The method works on simple estimators as well as on nested objects (such as :class:`~sklearn.pipeline.Pipeline`). The latter have parameters of the form ``__`` so that it's possible to update each component of a nested object. :Parameters: **\*\*params** : dict Estimator parameters. :Returns: **self** : estimator instance Estimator instance. .. !! processed by numpydoc !! .. py:class:: ShapeletForestCounterfactual(*, cost='euclidean', aggregation='mean', epsilon=1.0, batch_size=0.1, max_paths=1.0, verbose=False, random_state=None) Counterfactual explanations for shapelet forest classifiers. :Parameters: **cost** : {"euclidean", "cosine", "manhattan"} or callable, optional The cost function to determine the goodness of counterfactual. **aggregation** : callable, optional The aggregation function for the cost of multivariate counterfactuals. **epsilon** : float, optional Control the degree of change from the decision threshold. **batch_size** : float, optional Batch size when evaluating the cost and predictions of counterfactual candidates. The default setting is to evaluate all counterfactual samples. .. versionchanged:: 1.1 The default value changed to 0.1 **max_paths** : float, optional Sample a fraction of the positive prediction paths. .. versionadded:: 1.1 Add support for subsampling prediction paths. **verbose** : bool, optional Print information to stdout during execution. **random_state** : RandomState or int, optional Pseudo-random number for consistency between different runs. .. warning:: Only shapelet forests fit with the Euclidean distance is supported i.e., ``metric="euclidean"`` .. rubric:: Notes This implementation only supports the reversible algorithm described by Karlsson (2020) .. rubric:: References Karlsson, I., Rebane, J., Papapetrou, P., & Gionis, A. (2020). Locally and globally explainable time series tweaking. Knowledge and Information Systems, 62(5), 1671-1700. Karlsson, I., Rebane, J., Papapetrou, P., & Gionis, A. (2018). Explainable time series tweaking via irreversible and reversible temporal transformations. In 2018 IEEE International Conference on Data Mining (ICDM) .. only:: latex :Attributes: **paths_** : dict A dictionary of prediction paths per label .. !! processed by numpydoc !! .. py:method:: fit_explain(estimator, x=None, y=None, **kwargs) Fit and return the explanation. :Parameters: **estimator** : Estimator The estimator to explain. **x** : time-series, optional The input time series. **y** : array-like of shape (n_samples, ), optional The labels. **\*\*kwargs** Optional extra arguments. :Returns: ndarray The explanation. .. !! processed by numpydoc !! .. py:method:: get_metadata_routing() Get metadata routing of this object. Please check :ref:`User Guide ` on how the routing mechanism works. :Returns: **routing** : MetadataRequest A :class:`~sklearn.utils.metadata_routing.MetadataRequest` encapsulating routing information. .. !! processed by numpydoc !! .. py:method:: get_params(deep=True) Get parameters for this estimator. :Parameters: **deep** : bool, default=True If True, will return the parameters for this estimator and contained subobjects that are estimators. :Returns: **params** : dict Parameter names mapped to their values. .. !! processed by numpydoc !! .. py:method:: plot(x=None, y=None, ax=None) Plot the explanation. :Returns: **ax** : Axes The axes object .. !! processed by numpydoc !! .. py:method:: score(x, y) Score the counterfactual explainer in terms of closeness of fit. :Parameters: **x** : array-like of shape (n_samples, n_timestep) The samples. **y** : array-like of shape (n_samples, ) The desired counterfactal label. :Returns: **score** : float The closensess of fit. .. !! processed by numpydoc !! .. py:method:: set_params(**params) Set the parameters of this estimator. The method works on simple estimators as well as on nested objects (such as :class:`~sklearn.pipeline.Pipeline`). The latter have parameters of the form ``__`` so that it's possible to update each component of a nested object. :Parameters: **\*\*params** : dict Estimator parameters. :Returns: **self** : estimator instance Estimator instance. .. !! processed by numpydoc !! .. py:function:: counterfactuals(estimator, x, y, *, train_x=None, train_y=None, method='best', scoring='deprecated', valid_scoring='deprecated', proximity=None, random_state=None, method_args=None) Compute a single counterfactual example for each sample. :Parameters: **estimator** : object The estimator used to compute the counterfactual example. **x** : array-like of shape (n_samples, n_timestep) The data samples to fit counterfactuals to. **y** : array-like broadcast to shape (n_samples,) The desired label of the counterfactual. **train_x** : array-like of shape (n_samples, n_timestep), optional Training samples if required by the explainer. **train_y** : array-like of shape (n_samples, ), optional Training labels if required by the explainer. **method** : str or BaseCounterfactual, optional The method to generate counterfactual explanations - if 'best', infer the most appropriate counterfactual explanation method based on the estimator. .. versionchanged:: 1.1.0 - if str, select counterfactual explainer from named collection. See ``_COUNTERFACTUALS.keys()`` for a list of valid values. - if, BaseCounterfactual use the supplied counterfactual. **scoring** : str, callable, list or dict, optional The scoring function to determine the similarity between the counterfactual sample and the original sample. .. deprecated:: 1.1 ``scoring`` was renamed to ``proximity`` in 1.1 and will be removed in 1.2. **valid_scoring** : bool, optional Only compute score for successful counterfactuals. .. deprecated:: 1.1 ``valid_scoring`` will be removed in 1.2. **proximity** : str, callable, list or dict, optional The scoring function to determine the similarity between the counterfactual sample and the original sample. **random_state** : RandomState or int, optional The pseudo random number generator to ensure stable result. **method_args** : dict, optional Optional arguments to the counterfactual explainer. .. versionadded:: 1.1.0 :Returns: **x_counterfactuals** : ndarray of shape (n_samples, n_timestep) The counterfactual example. **valid** : ndarray of shape (n_samples,) Indicator matrix for valid counterfactuals. **score** : ndarray of shape (n_samples,) or dict, optional Return score of the counterfactual transform, if ``scoring`` is not None. .. !! processed by numpydoc !! .. py:function:: proximity(x_true, x_counterfactuals, metric='normalized_euclidean', metric_params=None) Compute the proximity of the counterfactuals. :Parameters: **x_true** : array-like of shape (n_samples, n_timestep) The true samples. **x_counterfactuals** : array-like of shape (n_samples, n_timestep) The counterfactual samples. **metric** : str or callable, optional The distance metric See ``_METRICS.keys()`` for a list of supported metrics. **metric_params** : dict, optional Parameters to the metric. Read more about the parameters in the :ref:`User guide `. :Returns: ndarray The scores. .. !! processed by numpydoc !!