docstr: Explains a foreground time series and returns a :class:`ShapExplainabilityResult
  <darts.explainability.explainability_result.ShapExplainabilityResult>`.
  The results can be retrieved with method :func:`get_explanation()
  <darts.explainability.explainability_result.ShapExplainabilityResult.get_explanation>`.
  The result is a multivariate `TimeSeries` instance containing the 'explanation'
  for the (horizon, target_component) forecast at any timestamp forecastable corresponding to
  the foreground `TimeSeries` input.
  
  The component name convention of this multivariate `TimeSeries` is:
  ``"{name}_{type_of_cov}_lag_{idx}"``, where:
  
  - ``{name}`` is the component name from the original foreground series (target, past, or future).
  - ``{type_of_cov}`` is the covariates type. It can take 3 different values:
    ``"target"``, ``"past_cov"`` or ``"future_cov"``.
  - ``{idx}`` is the lag index.
  
  Parameters
  ----------
  foreground_series
      Optionally, one or a sequence of target `TimeSeries` to be explained. Can be multivariate.
      If not provided, the background `TimeSeries` will be explained instead.
  foreground_past_covariates
      Optionally, one or a sequence of past covariates `TimeSeries` if required by the forecasting model.
  foreground_future_covariates
      Optionally, one or a sequence of future covariates `TimeSeries` if required by the forecasting model.
  horizons
      Optionally, an integer or sequence of integers representing the future time steps to be explained.
      `1` corresponds to the first timestamp being forecasted.
      All values must be `<=output_chunk_length` of the explained forecasting model.
  target_components
      Optionally, a string or sequence of strings with the target components to explain.
  
  Returns
  -------
  ShapExplainabilityResult
      The forecast explanations
  
  Examples
  --------
  Say we have a model with 2 target components named ``"T_0"`` and ``"T_1"``,
  3 past covariates with default component names ``"0"``, ``"1"``, and ``"2"``,
  and one future covariate with default component name ``"0"``.
  Also, ``horizons = [1, 2]``.
  The model is a regression model, with ``lags = 3``, ``lags_past_covariates=[-1, -3]``,
  ``lags_future_covariates = [0]``.
  
  We provide `foreground_series`, `foreground_past_covariates`, `foreground_future_covariates` each of length 5.
  
  >>> explain_results = explainer.explain(
  >>>     foreground_series=foreground_series,
  >>>     foreground_past_covariates=foreground_past_covariates,
  >>>     foreground_future_covariates=foreground_future_covariates,
  >>>     horizons=[1, 2],
  >>>     target_names=["T_0", "T_1"])
  >>> output = explain_results.get_explanation(horizon=1, component="T_1")
  >>> feature_values = explain_results.get_feature_values(horizon=1, component="T_1")
  >>> shap_objects = explain_results.get_shap_explanation_objects(horizon=1, component="T_1")
  
  Then the method returns a multivariate TimeSeries containing the *explanations* of
  the `ShapExplainer`, with the following component names:
  
       - T_0_target_lag-1
       - T_0_target_lag-2
       - T_0_target_lag-3
       - T_1_target_lag-1
       - T_1_target_lag-2
       - T_1_target_lag-3
       - 0_past_cov_lag-1
       - 0_past_cov_lag-3
       - 1_past_cov_lag-1
       - 1_past_cov_lag-3
       - 2_past_cov_lag-1
       - 2_past_cov_lag-3
       - 0_fut_cov_lag_0
  
  This series has length 3, as the model can explain 5-3+1 forecasts
  (timestamp indexes 4, 5, and 6)
docstr_tok: ["Explains","a","foreground","time","series","and","returns","a",":","class",":","`","ShapExplainabilityResult","<","darts.explainability.explainability_result.ShapExplainabilityResult",">","`",".","The","results","can","be","retrieved","with","method",":","func",":","`","get_explanation","(",")","<","darts.explainability.explainability_result.ShapExplainabilityResult.get_explanation",">","`",".","The","result","is","a","multivariate","`","TimeSeries","`","instance","containing","the","'explanation'","for","the","(","horizon",",","target_component",")","forecast","at","any","timestamp","forecastable","corresponding","to","the","foreground","`","TimeSeries","`","input",".","The","component","name","convention","of","this","multivariate","`","TimeSeries","`","is",":","``","``","{","name","}","_","{","type_of_cov","}","_lag_","{","idx","}","''","``",",","where",":","-","``","{","name","}","``","is","the","component","name","from","the","original","foreground","series","(","target",",","past",",","or","future",")",".","-","``","{","type_of_cov","}","``","is","the","covariates","type",".","It","can","take","3","different","values",":","``","``","target","''","``",",","``","``","past_cov","''","``","or","``","``","future_cov","''","``",".","-","``","{","idx","}","``","is","the","lag","index",".","Parameters","--","--","--","--","--","foreground_series","Optionally",",","one","or","a","sequence","of","target","`","TimeSeries","`","to","be","explained",".","Can","be","multivariate",".","If","not","provided",",","the","background","`","TimeSeries","`","will","be","explained","instead",".","foreground_past_covariates","Optionally",",","one","or","a","sequence","of","past","covariates","`","TimeSeries","`","if","required","by","the","forecasting","model",".","foreground_future_covariates","Optionally",",","one","or","a","sequence","of","future","covariates","`","TimeSeries","`","if","required","by","the","forecasting","model",".","horizons","Optionally",",","an","integer","or","sequence","of","integers","representing","the","future","time","steps","to","be","explained",".","`","1","`","corresponds","to","the","first","timestamp","being","forecasted",".","All","values","must","be","`","<","=output_chunk_length","`","of","the","explained","forecasting","model",".","target_components","Optionally",",","a","string","or","sequence","of","strings","with","the","target","components","to","explain",".","Returns","--","--","--","-","ShapExplainabilityResult","The","forecast","explanations","Examples","--","--","--","--","Say","we","have","a","model","with","2","target","components","named","``","``","T_0","''","``","and","``","``","T_1","''","``",",","3","past","covariates","with","default","component","names","``","``","0","''","``",",","``","``","1","''","``",",","and","``","``","2","''","``",",","and","one","future","covariate","with","default","component","name","``","``","0","''","``",".","Also",",","``","horizons","=","[","1",",","2","]","``",".","The","model","is","a","regression","model",",","with","``","lags","=","3","``",",","``","lags_past_covariates=","[","-1",",","-3","]","``",",","``","lags_future_covariates","=","[","0","]","``",".","We","provide","`","foreground_series","`",",","`","foreground_past_covariates","`",",","`","foreground_future_covariates","`","each","of","length","5",".",">",">",">","explain_results","=","explainer.explain","(",">",">",">","foreground_series=foreground_series",",",">",">",">","foreground_past_covariates=foreground_past_covariates",",",">",">",">","foreground_future_covariates=foreground_future_covariates",",",">",">",">","horizons=","[","1",",","2","]",",",">",">",">","target_names=","[","``","T_0","''",",","``","T_1","''","]",")",">",">",">","output","=","explain_results.get_explanation","(","horizon=1",",","component=","''","T_1","''",")",">",">",">","feature_values","=","explain_results.get_feature_values","(","horizon=1",",","component=","''","T_1","''",")",">",">",">","shap_objects","=","explain_results.get_shap_explanation_objects","(","horizon=1",",","component=","''","T_1","''",")","Then","the","method","returns","a","multivariate","TimeSeries","containing","the","*","explanations","*","of","the","`","ShapExplainer","`",",","with","the","following","component","names",":","-","T_0_target_lag-1","-","T_0_target_lag-2","-","T_0_target_lag-3","-","T_1_target_lag-1","-","T_1_target_lag-2","-","T_1_target_lag-3","-","0_past_cov_lag-1","-","0_past_cov_lag-3","-","1_past_cov_lag-1","-","1_past_cov_lag-3","-","2_past_cov_lag-1","-","2_past_cov_lag-3","-","0_fut_cov_lag_0","This","series","has","length","3",",","as","the","model","can","explain","5-3+1","forecasts","(","timestamp","indexes","4",",","5",",","and","6",")"]
code: def explain(
      self,
      foreground_series: Optional[
          Union[TimeSeries, Sequence[TimeSeries]]
      ] = None,
      foreground_past_covariates: Optional[
          Union[TimeSeries, Sequence[TimeSeries]]
      ] = None,
      foreground_future_covariates: Optional[
          Union[TimeSeries, Sequence[TimeSeries]]
      ] = None,
      horizons: Optional[Sequence[int]] = None,
      target_components: Optional[Sequence[str]] = None,
  ) -> ShapExplainabilityResult:
      """
      Explains a foreground time series and returns a :class:`ShapExplainabilityResult
      <darts.explainability.explainability_result.ShapExplainabilityResult>`.
      The results can be retrieved with method :func:`get_explanation()
      <darts.explainability.explainability_result.ShapExplainabilityResult.get_explanation>`.
      The result is a multivariate `TimeSeries` instance containing the 'explanation'
      for the (horizon, target_component) forecast at any timestamp forecastable corresponding to
      the foreground `TimeSeries` input.
  
      The component name convention of this multivariate `TimeSeries` is:
      ``"{name}_{type_of_cov}_lag_{idx}"``, where:
  
      - ``{name}`` is the component name from the original foreground series (target, past, or future).
      - ``{type_of_cov}`` is the covariates type. It can take 3 different values:
        ``"target"``, ``"past_cov"`` or ``"future_cov"``.
      - ``{idx}`` is the lag index.
  
      Parameters
      ----------
      foreground_series
          Optionally, one or a sequence of target `TimeSeries` to be explained. Can be multivariate.
          If not provided, the background `TimeSeries` will be explained instead.
      foreground_past_covariates
          Optionally, one or a sequence of past covariates `TimeSeries` if required by the forecasting model.
      foreground_future_covariates
          Optionally, one or a sequence of future covariates `TimeSeries` if required by the forecasting model.
      horizons
          Optionally, an integer or sequence of integers representing the future time steps to be explained.
          `1` corresponds to the first timestamp being forecasted.
          All values must be `<=output_chunk_length` of the explained forecasting model.
      target_components
          Optionally, a string or sequence of strings with the target components to explain.
  
      Returns
      -------
      ShapExplainabilityResult
          The forecast explanations
  
      Examples
      --------
      Say we have a model with 2 target components named ``"T_0"`` and ``"T_1"``,
      3 past covariates with default component names ``"0"``, ``"1"``, and ``"2"``,
      and one future covariate with default component name ``"0"``.
      Also, ``horizons = [1, 2]``.
      The model is a regression model, with ``lags = 3``, ``lags_past_covariates=[-1, -3]``,
      ``lags_future_covariates = [0]``.
  
      We provide `foreground_series`, `foreground_past_covariates`, `foreground_future_covariates` each of length 5.
  
      >>> explain_results = explainer.explain(
      >>>     foreground_series=foreground_series,
      >>>     foreground_past_covariates=foreground_past_covariates,
      >>>     foreground_future_covariates=foreground_future_covariates,
      >>>     horizons=[1, 2],
      >>>     target_names=["T_0", "T_1"])
      >>> output = explain_results.get_explanation(horizon=1, component="T_1")
      >>> feature_values = explain_results.get_feature_values(horizon=1, component="T_1")
      >>> shap_objects = explain_results.get_shap_explanation_objects(horizon=1, component="T_1")
  
      Then the method returns a multivariate TimeSeries containing the *explanations* of
      the `ShapExplainer`, with the following component names:
  
           - T_0_target_lag-1
           - T_0_target_lag-2
           - T_0_target_lag-3
           - T_1_target_lag-1
           - T_1_target_lag-2
           - T_1_target_lag-3
           - 0_past_cov_lag-1
           - 0_past_cov_lag-3
           - 1_past_cov_lag-1
           - 1_past_cov_lag-3
           - 2_past_cov_lag-1
           - 2_past_cov_lag-3
           - 0_fut_cov_lag_0
  
      This series has length 3, as the model can explain 5-3+1 forecasts
      (timestamp indexes 4, 5, and 6)
      """
      super().explain(
          foreground_series,
          foreground_past_covariates,
          foreground_future_covariates,
      )
      (
          foreground_series,
          foreground_past_covariates,
          foreground_future_covariates,
          _,
          _,
          _,
          _,
      ) = self._process_foreground(
          foreground_series,
          foreground_past_covariates,
          foreground_future_covariates,
      )
      horizons, target_names = self._process_horizons_and_targets(
          horizons,
          target_components,
      )
  
      shap_values_list = []
      feature_values_list = []
      shap_explanation_object_list = []
      for idx, foreground_ts in enumerate(foreground_series):
          foreground_past_cov_ts = None
          foreground_future_cov_ts = None
  
          if foreground_past_covariates:
              foreground_past_cov_ts = foreground_past_covariates[idx]
  
          if foreground_future_covariates:
              foreground_future_cov_ts = foreground_future_covariates[
                  idx
              ]
  
          foreground_X = (
              self.explainers._create_regression_model_shap_X(
                  foreground_ts,
                  foreground_past_cov_ts,
                  foreground_future_cov_ts,
                  train=False,
              )
          )
  
          shap_ = self.explainers.shap_explanations(
              foreground_X, horizons, target_names
          )
  
          shap_values_dict = {}
          feature_values_dict = {}
          shap_explanation_object_dict = {}
          for h in horizons:
              shap_values_dict_single_h = {}
              feature_values_dict_single_h = {}
              shap_explanation_object_dict_single_h = {}
              for t in target_names:
                  shap_values_dict_single_h[
                      t
                  ] = TimeSeries.from_times_and_values(
                      shap_[h][t].time_index,
                      shap_[h][t].values,
                      columns=shap_[h][t].feature_names,
                  )
                  feature_values_dict_single_h[
                      t
                  ] = TimeSeries.from_times_and_values(
                      shap_[h][t].time_index,
                      shap_[h][t].data,
                      columns=shap_[h][t].feature_names,
                  )
                  shap_explanation_object_dict_single_h[t] = shap_[h][t]
              shap_values_dict[h] = shap_values_dict_single_h
              feature_values_dict[h] = feature_values_dict_single_h
              shap_explanation_object_dict[
                  h
              ] = shap_explanation_object_dict_single_h
  
          shap_values_list.append(shap_values_dict)
          feature_values_list.append(feature_values_dict)
          shap_explanation_object_list.append(
              shap_explanation_object_dict
          )
  
      if len(shap_values_list) == 1:
          shap_values_list = shap_values_list[0]
          feature_values_list = feature_values_list[0]
          shap_explanation_object_list = shap_explanation_object_list[0]
  
      return ShapExplainabilityResult(
          shap_values_list,
          feature_values_list,
          shap_explanation_object_list,
      )
  
imports: from enum import Enum
  from typing import Dict, NewType, Optional, Sequence, Union
  import matplotlib.pyplot
  import pandas
  import shap
  from sklearn.multioutput import MultiOutputRegressor
  from darts import TimeSeries
  from darts.explainability.explainability import _ForecastingModelExplainer
  from darts.explainability.explainability_result import ShapExplainabilityResult
  from darts.logging import get_logger, raise_if, raise_log
  from darts.models.forecasting.regression_model import RegressionModel
  from darts.utils.data.tabularization import create_lagged_prediction_data
label_desc: Use image node_id 2 for calling the ShapExplainer obj's underlying member method code with example usage: obj.explain(foreground_series, foreground_past_covariates, foreground_future_covariates, horizons, target_components) and returns: ShapExplainabilityResult