**************************
:py:mod:`wildboar.explain`
**************************

.. py:module:: wildboar.explain

.. autoapi-nested-parse::

   
   Explanation methods for classifiers and regressors.
















   ..
       !! processed by numpydoc !!



Classes
-------

.. autoapisummary::

   wildboar.explain.AmplitudeImportance
   wildboar.explain.FrequencyImportance
   wildboar.explain.IntervalImportance
   wildboar.explain.ShapeletImportance



Functions
---------

.. autoapisummary::

   wildboar.explain.plot_importances




.. raw:: html

   <br />

.. py:class:: AmplitudeImportance(scoring=None, n_intervals='sqrt', window=None, binning='normal', n_bins=4, n_repeat=1, random_state=None)



   
   Compute the importance of equi-probable amplitude intervals.

   The implementation uses
   :class:`transform.SAX` to discretize the time series and then for each bin permute
   the samples along that bin.















   ..
       !! 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** : dict, optional
              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 <metadata_routing>` 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, n_samples=100, scoring=None, preprocess=True, k=None, show_bins=False, show_grid=True)

      
      Plot the importances.

      If x is given, the importances are plotted over the samples optionally
      labeling each sample using the supplied labels. If x is not give, the
      importances are plotted as one or more boxplots.

      :Parameters:

          **x** : array-like of shape (n_samples, n_timesteps), optional
              The samples.

          **y** : array-like of shape (n_samples, ), optional
              The labels.

          **ax** : Axes, optional
              Axes to plot. If ax is set, x is None and scoring is None, the number of
              axes must be the same as the number of scorers.

          **n_samples** : int or float, optional
              The number of samples to plot, set to `None` to plot all.

          **scoring** : str, optional
              The scoring to plot if multiple scorers were used when fitting.

          **preprocess** : bool, optional
              Preprocess the time series to align with the bins, ignored if x is not None.

          **k** : int or float, optional
              The number of top bins to plot, ignored if x is not None.
              
              - if int, the specified number of bins are shown
              - if float, a fraction of the number of bins are shown.

          **show_bins** : bool, optional
              Annotate the plot with the index of the bin, ignored if x is not None.

          **show_grid** : bool, optional
              Annotate the plot with the bin thresholds, ignored if x is not None.



      :Returns:

          **ax** : Axis
              The axis.

          **mappable** : ScalarMappable, optional
              Return the mappable used to plot the colorbar.
              Only returned if ax is not None and x is not None.











      ..
          !! 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 ``<component>__<parameter>`` 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:: FrequencyImportance(scoring=None, n_repeat=5, random_state=None, n_bands=10, spectrum='amplitude', growth_factor=np.e)



   
   Explainer to evaluate feature importance based on frequency bands.

   This class implements a frequency-based importance measure by permuting values
   within frequency bands obtained from the Fourier transform of time series data.
   It extends PermuteImportance to analyze the impact of different frequency
   components on model predictions.

   :Parameters:

       **scoring** : str, callable, or None, optional
           Scoring metric to evaluate importance. If None, uses estimator's score method.

       **n_repeat** : int, optional
           Number of times to permute each frequency band.

       **random_state** : int, RandomState instance or None, optional
           Controls randomization for permutations.

       **n_bands** : int, optional
           Number of frequency bands to analyze.

       **spectrum** : {"amplitude", "phase"}, optional
           Whether to permute amplitude components or to permute phase components.

       **growth_factor** : float, optional
           Controls growth of frequency band sizes:
           - growth_factor > 1: exponential growth (more detail at lower frequencies)
           - growth_factor = 1: linear growth (equal-sized bands)
           - growth_factor < 1: logarithmic decay (more detail at higher frequencies)
           
           Defaults to `np.e`.

   :Attributes:

       **components_** : list of tuples
           The frequency bands used for permutation, as (start, end) indices.

       **importances_** : ImportanceContainer
           Contains the calculated feature importance scores.

       **n_timesteps_in_** : int
           Number of timesteps in the input data.









   .. seealso::

       
       :obj:`PermuteImportance`
           Base class for permutation-based importance.
       
       
   .. rubric:: Notes

   The frequency bands are constructed by dividing the frequency domain into windows,
   with the size of each window controlled by the growth_factor parameter. This allows
   for analyzing different scales of temporal patterns in the data.



   ..
       !! 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** : dict, optional
              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 <metadata_routing>` 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, k=None, sample_spacing=1, jitter=False)

      
      Plot the explanation.


      :Parameters:

          **x** : array-like, optional
              Optional imput samples.

          **y** : array-like, optional
              Optional target labels.

          **ax** : Axes, optional
              Optional axes to plot to.



      :Returns:

          Axes
              The axes object.











      ..
          !! 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 ``<component>__<parameter>`` 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:: IntervalImportance(*, scoring=None, n_repeat=5, n_intervals='sqrt', window=None, random_state=None)



   
   Interval importance for time series.


   :Parameters:

       **scoring** : str, list, dict or callable, optional
           The scoring function. By default the estimators score function is used.

       **n_repeat** : int, optional
           The number of repeated permutations.

       **n_intervals** : str, optional
           The number of intervals.
           
           - if "sqrt", the number of intervals is the square root of n_timestep.
           - if "log2", the number of intervals is the log2 of n_timestep.
           - if int, exact number of intervals.

       **window** : int, optional
           The window size. If specicied, n_intervals is ignored and the number of
           intervals is computed such that each interval is (at least) of size window.

       **random_state** : int or RandomState
           - 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`.

   :Attributes:

       **importances_** : dict or Importance
           The importance scores for each interval. If dict, one value per scoring
           function.

       **components_** : ndarray of shape (n_intervals, 2)
           The interval start and end positions.













   ..
       !! 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** : dict, optional
              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 <metadata_routing>` 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, scoring=None, k=None, n_samples=100, show_grid=True)

      
      Plot the explanation.


      :Parameters:

          **x** : array-like, optional
              Optional imput samples.

          **y** : array-like, optional
              Optional target labels.

          **ax** : Axes, optional
              Optional axes to plot to.



      :Returns:

          Axes
              The axes object.











      ..
          !! 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 ``<component>__<parameter>`` 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:: ShapeletImportance(scoring=None, n_repeat=1, n_shapelets=10, min_shapelet_size=0.0, max_shapelet_size=1.0, coverage_probability=None, variability=1, metric='euclidean', metric_params=None, random_state=None)



   
   Compute the importance of shapelets.

   The importance is given by permuting time series sections with
   the minimum distance to shapelets.

   :Parameters:

       **scoring** : str, list, dict or callable, optional
           The scoring function. By default the estimators score function is used.

       **n_repeat** : int, optional
           The number of repeated permutations.

       **n_shapelets** : int, optional
           The number of shapelets to sample for the explanation.

       **min_shapelet_size** : float, optional
           The minimum size of shapelets used for explanation.

       **max_shapelet_size** : float, optional
           The maximum size of shapelets used for explanation.

       **coverage_probability** : float, optional
           The probability that a time step is covered by a
           shapelet, in the range 0 < coverage_probability <= 1.
           
           - For larger `coverage_probability`, we get larger shapelets.
           - For smaller `coverage_probability`, we get shorter shapelets.

       **variability** : float, optional
           Controls the shape of the Beta distribution used to
           sample shapelets. Defaults to 1.
           
           - Higher `variability` creates more uniform intervals.
           - Lower `variability` creates more variable intervals sizes.

       **metric** : str, optional
           The metric.

       **metric_params** : str, optional
           The metric parameters.

       **random_state** : int or RandomState, optional
           Controls the random resampling of the original dataset.
           
           - If `int`, `random_state` is the seed used by the
             random number generator.
           - If :class:`numpy.random.RandomState` instance, `random_state` is the
             random number generator.
           - If `None`, the random number generator is the
             :class:`numpy.random.RandomState` instance used by
             :func:`numpy.random`.

   :Attributes:

       **components** : ndarray
           The shapelets













   ..
       !! 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** : dict, optional
              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 <metadata_routing>` 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, k=None, scoring=None, kernel_scale=0.25, ax=None)

      
      Plot the explanation.


      :Parameters:

          **x** : array-like, optional
              Optional imput samples.

          **y** : array-like, optional
              Optional target labels.

          **ax** : Axes, optional
              Optional axes to plot to.



      :Returns:

          Axes
              The axes object.











      ..
          !! 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 ``<component>__<parameter>`` 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:: plot_importances(importances, ax=None, labels=None)

   
   Plot the importances as a boxplot.


   :Parameters:

       **importances** : Importance or dict
           The importances.

       **ax** : Axes, optional
           The axes to plot. If importances is dict, ax must contain at least
           len(importances) Axes objects.

       **labels** : array-like, optional
           The labels for the importances.



   :Returns:

       Axes
           The plotted Axes.











   ..
       !! processed by numpydoc !!