dianna.visualization
====================

.. py:module:: dianna.visualization

.. autoapi-nested-parse::

   Tools for visualization of model explanations.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/dianna/visualization/image/index
   /autoapi/dianna/visualization/tabular/index
   /autoapi/dianna/visualization/text/index
   /autoapi/dianna/visualization/timeseries/index


Functions
---------

.. autoapisummary::

   dianna.visualization.plot_image
   dianna.visualization.plot_tabular
   dianna.visualization.highlight_text
   dianna.visualization.plot_timeseries


Package Contents
----------------

.. py:function:: plot_image(heatmap: numpy.ndarray, original_data: Optional[numpy.ndarray] = None, heatmap_cmap='bwr', heatmap_range=(None, None), data_cmap=None, show_plot: bool = True, output_filename=None, ax: Optional[matplotlib.pyplot.Axes] = None) -> matplotlib.pyplot.Figure

   Plots a heatmap image.

   Optionally, the heatmap (typically a saliency map of an explainer) can be
   plotted on top of the original data. In that case both images are plotted
   transparantly with alpha = 0.5.

   :param heatmap: the saliency map or other heatmap to be plotted.
   :param original_data: the data to plot together with the heatmap, both with
                         alpha = 0.5 (optional).
   :param heatmap_cmap: color map for the heatmap plot (see mpl.Axes.imshow
                        documentation for options).
   :param heatmap_range: a tuple (vmin, vmax) to set the range of the heatmap.
                         By default, the colormap covers the complete value range of
                         the supplied heatmap.
   :param data_cmap: color map for the (optional) data image (see mpl.Axes.imshow
                     documentation for options). By default, if the image is two
                     dimensional, the color map is set to 'gray'.
   :param show_plot: Shows plot if true (for testing or writing plots to disk
                     instead).
   :param output_filename: Name of the file to save the plot to (optional).
   :param ax: matplotlib.Axes object to plot on (optional).

   :returns: None


.. py:function:: plot_tabular(x: numpy.ndarray, y: List[str], x_label: str = 'Importance score', y_label: str = 'Features', num_features: Optional[int] = None, show_plot: Optional[bool] = True, output_filename: Optional[str] = None, ax: Optional[matplotlib.pyplot.Axes] = None) -> matplotlib.pyplot.Figure

   Plot feature importance with segments highlighted.

   :param x: 1D array of feature importance scores of one instance
   :type x: np.ndarray
   :param y: List of feature names
   :type y: List[str]
   :param x_label: Label for the x-axis
   :type x_label: str
   :param y_label: Label or list of labels for the y-axis
   :type y_label: str
   :param num_features: Number of most salient features to display
   :type num_features: Optional[int]
   :param show_plot: Shows plot if true (for testing or writing
                     plots to disk instead).
   :type show_plot: bool, optional
   :param output_filename: Name of the file to save
                           the plot to (optional).
   :type output_filename: str, optional
   :param ax: externally created canvas to plot on.
   :type ax: matplotlib.Axes, optional

   :returns: plt.Figure


.. py:function:: highlight_text(explanation, input_tokens=None, show_plot=True, output_filename=None, colormap='bwr', alpha=1.0, heatmap_range=(-1, 1))

   Highlights a given text based on values in a given explanation object.

   :param explanation: list of tuples of (word, index of word in original data, importance)
   :param input_tokens: list of all tokens (including those without importance)
   :param show_plot: Shows plot if true (for testing or writing plots to disk instead)
   :param output_filename: Name of the file to save the plot to (optional).
   :param colormap: color map for the heatmap plot (see mpl.Axes.imshow documentation for options).
   :param alpha: alpha value for the heatmap plot.
   :param heatmap_range: a tuple (vmin, vmax) to set the range of the heatmap.

   :returns: None


.. py:function:: plot_timeseries(x: numpy.ndarray, y: numpy.ndarray, segments: List[Dict[str, Any]], x_label: str = 't', y_label: Union[str, Iterable[str]] = None, cmap: Optional[str] = 'bwr', show_plot: Optional[bool] = True, output_filename: Optional[str] = None, heatmap_range=(-1, 1)) -> matplotlib.pyplot.Figure

   Plot timeseries with segments highlighted.

   :param x: X-values with shape (number of time_steps)
   :type x: np.ndarray
   :param y: Y-values with shape (number_of_time_steps, number_of_channels)
   :type y: np.ndarray
   :param segments: Segment data, must be a list of
                    dicts with the following keys: 'index', 'start', 'end',
                    'weight', 'channel. Here, `index` is the index of the segment of feature,
                    `start` and `end` determine the location of the
                    segment, `weight` determines the color, and 'channel' determines the channel within the timeseries.
   :type segments: List[Dict[str, Any]]
   :param x_label: Label for the x-axis
   :type x_label: str, optional
   :param y_label: Label or list of labels for the y-axis
   :type y_label: Union[str, Iterable[str]], optional
   :param cmap: Matplotlib colormap
   :type cmap: str, optional
   :param show_plot: Shows plot if true (for testing or writing
                     plots to disk instead).
   :type show_plot: bool, optional
   :param output_filename: Name of the file to save
                           the plot to (optional).
   :type output_filename: str, optional
   :param heatmap_range: a tuple (vmin, vmax) to set the range of the heatmap.
   :type heatmap_range: tuple, optional

   :returns: plt.Figure