lime_timeseries
===============

.. py:module:: lime_timeseries


Classes
-------

.. autoapisummary::

   lime_timeseries.LIMETimeseries


Module Contents
---------------

.. py:class:: LIMETimeseries(kernel_width=25, verbose=False, preprocess_function=None, feature_selection='auto', random_state=None)

   LIME implementation for timeseries.

   This implementation is inspired by the paper:
   Validation of XAI explanations for multivariate time series classification in
   the maritime domain. (https://doi.org/10.1016/j.jocs.2021.101539)


   .. py:attribute:: explainer


   .. py:attribute:: feature_selection


   .. py:attribute:: domain_mapper


   .. py:attribute:: preprocess_function


   .. py:attribute:: _is_multivariate
      :value: False



   .. py:method:: explain(model_or_function, input_timeseries, labels=(0, ), class_names=None, num_features=1, num_samples=1, num_slices=1, batch_size=1, mask_type='mean', distance_method='cosine')

      Run the LIME explainer for timeseries.

      :param model_or_function: The function that runs the model to be explained _or_
                                the path to a ONNX model on disk.
      :type model_or_function: callable or str
      :param input_timeseries: The input time series data to be explained, with shape
                               [batch_size, sequence_length, num_features].
      :type input_timeseries: np.ndarray
      :param labels: The list of labels for different classes.
      :type labels: list
      :param class_names: The list of class names.
      :type class_names: list
      :param num_features: The number of features to include in the explanation.
      :type num_features: int
      :param num_samples: The number of samples to generate for the LIME explainer.
      :type num_samples: int
      :param num_slices: The number of slices to divide the time series data into.
      :type num_slices: int
      :param batch_size: The batch size to use for running the model.
      :type batch_size: int
      :param mask_type: The type of mask to apply to the time series data. Can be "mean" or "noise".
      :type mask_type: str
      :param distance_method: The distance metric to use for LIME. Can be "cosine" or "euclidean".
      :type distance_method: str

      :returns: An array (np.ndarray) containing the LIME explanations for each class.
      :rtype: np.ndarray



   .. py:method:: _calculate_distance(masked_data, distance_method='cosine')

      Calcuate distance between perturbed data and the original samples.

      :param masked_data: The perturbed time series data.
                          *Note: The first instance is the original timeseries
      :type masked_data: np.ndarray
      :param distance_method: The distance metric to use. Defaults to "cosine".
                              Supported options are:
                              - 'cosine': Computes the cosine similarity between the two vectors.
                              - 'euclidean': Computes the Euclidean distance between the two vectors.
                              - 'dtw': Uses Dynamic Time Warping to calculate the distance between
                                the two time series.
      :type distance_method: str

      :returns: A vector containing the distance between two timeseries.
      :rtype: np.ndarray

      :raises ValueError: If the given `distance_method` is not supported.

      .. rubric:: Notes

      - The cosine similarity is a measure of the similarity between two non-zero vectors
      of an inner product space that measures the cosine of the angle between them.
      - The Euclidean distance is the straight-line distance between two points in
        Euclidean space.
      - Dynamic Time Warping is an algorithm for measuring similarity between two time
        series sequences that may vary in speed or timing.



   .. py:method:: _dtw_distance(masked_data)

      Calculate distance based on dynamic time warping.

      :param masked_data: An array of time series with some segments masked out.
                          *Note: The first instance is the original timeseries
      :type masked_data: np.ndarray

      :returns: DTW distances.
      :rtype: np.ndarray