tft_torch.visualize module

Implements functional utilities which are helpful for visualizing the model outputs, both on a dataset level, and sample-wise

tft_torch.visualize.aggregate_weights(output_arr: numpy.ndarray, prctiles: List[float], feat_names: List[str]) → pandas.core.frame.DataFrame

Implements a utility function for aggregating selection weights for a set (array) of observations, whether these selection weights are associated with the static input attributes, or with a set of temporal selection weights. The aggregation of the weights is performed through the computation of several percentiles (provided by the caller) for describing the distribution of the weights, for each attribute.

Parameters

  • output_arr (np.ndarray) – A 2D or 3D array containing the selection weights output by the model. A 3D tensor will imply selection weights associated with temporal inputs.

  • prctiles (List[float]) – A list of percentiles according to which the distribution of selection weights will be described.

  • feat_names (List[str]) – A list of strings associated with the relevant attributes (according to the their order).

Returns

agg_df – A pandas dataframe, indexed with the relevant feature names, containing the aggregation of selection weights.

Return type

pd.DataFrame

tft_torch.visualize.display_selection_weights_stats(outputs_dict: Dict[str, numpy.ndarray], prctiles: List[float], mapping: Dict, sort_by: Optional[float] = None)

Implements a utility function for displaying the selection weights statistics of multiple input channels according to the outputs provided by the model for a set of input observations. It requires a mapping which specifies which output key corresponds to each input channel, and the associated list of attributes.

Parameters

  • outputs_dict (Dict[str,np.ndarray]) – A dictionary of numpy arrays containing the outputs of the model for a set of observations.

  • prctiles (List[float]) – A list of percentiles according to which the distribution of selection weights will be described.

  • mapping (Dict) – A dictionary specifying the output key corresponding to which input channel and the associated feature names.

  • sort_by (Optional[float]) – The percentile according to which the weights statistics will be sorted before displaying (Must be included as part of prctiles).

tft_torch.visualize.display_attention_scores(attention_scores: numpy.ndarray, horizons: Union[int, List[int]], prctiles: Union[float, List[float]], unit: Optional[str] = 'Units')

Implements a utility function for displaying the statistics of attention scores according to the outputs provided by the model for a set of input observations. The statistics of the scores will be described using specified percentiles, and for specified horizons.

Parameters

  • attention_scores (np.ndarray) – A numpy array containing the attention scores for the relevant dataset.

  • horizons (Union[int, List[int]]) – A list or a single horizon, specified in time-steps units, for which the statistics will be computed. If more than one horizon was configured, then only a single percentile computation will be allowed.

  • prctiles (Union[int, List[int]]) – A list or a single percentile to compute as a distribution describer for the scores. If more than percentile was configured, then only a single horizon will be allowed.

  • unit (Optional[str]) – The units associated with the time-steps. This variable is used for labeling the corresponding axes.

tft_torch.visualize.display_target_trajectory(signal_history: numpy.ndarray, signal_future: numpy.ndarray, model_preds: numpy.ndarray, observation_index: int, model_quantiles: List[float], transformation: Optional[Callable] = None, unit: Optional[str] = 'Units')

Implements a utility function for displaying, on a single observation level, the historical trajectory of the target variable, together with its future values, and the corresponding quantiles predicted by the model for each future time-step. In some cases, the target signal is transformed prior to training. For such cases, in order to allow visualization in the original scale of the target signal, a transformation function can be provided, for transforming the provided signals to the original scale.

Parameters

  • signal_history (np.ndarray) – A numpy array containing the historical values of the target signal.

  • signal_future (np.ndarray) – A numpy array containing the future values of the target signal (corresponding to the “labels”).

  • model_preds (np.ndarray) – A numpy array containing the predicted values by the model for each quantile.

  • observation_index (int) – The index corresponding to the observation for which the visualization will be generated.

  • model_quantiles (List[float]) – The list of quantiles configured in the trained model associated with the provided predictions.

  • transformation (Callable) – If provided, the function will be treated as a transformation, that will be applied to the provided signal before creating the visualization.

  • unit (Optional[str]) – The units associated with the time-steps. This variable is used for labeling the corresponding axes.

tft_torch.visualize.display_sample_wise_attention_scores(attention_scores: numpy.ndarray, observation_index: int, horizons: Union[int, List[int]], unit: Optional[str] = None)

Implements a utility function for displaying, on a single observation level, the attention scores output by the model, for, possibly, a multitude of horizons.

Parameters

  • attention_scores (np.ndarray) – A numpy array containing the attention scores for the relevant dataset.

  • observation_index (int) – The index with the dataset, corresponding to the observation for which the visualization will be generated.

  • horizons (Union[int, List[int]]) – A list or a single horizon, specified in time-steps units, for which the scores will be displayed.

  • unit (Optional[str]) – The units associated with the time-steps. This variable is used for labeling the corresponding axes.

tft_torch.visualize.display_sample_wise_selection_stats(weights_arr: numpy.ndarray, observation_index: int, feature_names: List[str], top_n: Optional[int] = None, title: Optional[str] = '', historical: Optional[bool] = True, rank_stepwise: Optional[bool] = False)

Implements a utility function for displaying, on a single observation level, the selection weights output by the model. This function can handle selection weights of both temporal input channels and static input channels.

Parameters

  • weights_arr (np.ndarray) – A 2D or 3D array containing the selection weights output by the model. A 3D tensor will implies selection weights associated with temporal inputs.

  • observation_index (int) – The index with the dataset, corresponding to the observation for which the visualization will be generated.

  • feature_names (List[str]) – A list of strings associated with the relevant attributes (according to the their order).

  • top_n (Optional[int]) – An integer specifying the quantity of the top weighted features to display.

  • title (Optional[str]) – A string which will be used when creating the title for the visualization.

  • historical (Optional[bool]) – Specifies whether the corresponding input channel contains historical data or future data. Relevant only for temporal input channels, and used for display purposes.

  • rank_stepwise (Optional[bool]) – Specifies whether to rank the features according to their weights, on each time-step separately, or simply display the raw selection weights output by the model. Relevant only for temporal input channels, and used for display purposes.