docs: add cross referencing to several plots functions (#3005)

* update beeswarm.py

* update bar.py

* update decision.py

* update force.py

* update heatmap.py

* update image.py

* update scatter.py

* update text.py

* update violin.py

* update waterfall.py

* update changelog entry

Author: thatlittleboy

CHANGELOG.md

@@ -45,7 +45,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ### Changed
 
 - Updates to docstrings of several `shap.plots` functions
-  ([#3003](https://github.com/slundberg/shap/pull/3003) by @thatlittleboy).
+  ([#3003](https://github.com/slundberg/shap/pull/3003),
+   [#3005](https://github.com/slundberg/shap/pull/3005) by @thatlittleboy).
 
 ### Removed
 

shap/plots/_bar.py

@@ -20,25 +20,31 @@
 # TODO: Have the Explanation object track enough data so that we can tell (and so show) how many instances are in each cohort
 def bar(shap_values, max_display=10, order=Explanation.abs, clustering=None, clustering_cutoff=0.5,
         merge_cohorts=False, show_data="auto", show=True):
-    """ Create a bar plot of a set of SHAP values.
+    """Create a bar plot of a set of SHAP values.
 
-    If a single sample is passed then we plot the SHAP values as a bar chart. If an
-    Explanation with many samples is passed then we plot the mean absolute value for
-    each feature column as a bar chart.
+    If a single sample is passed, then we plot the SHAP values as a bar chart. If an
+    :class:`.Explanation` with many samples is passed, then we plot the mean absolute
+    value for each feature column as a bar chart.
 
 
     Parameters
     ----------
     shap_values : shap.Explanation or shap.Cohorts or dictionary of shap.Explanation objects
-        A single row of a SHAP Explanation object (i.e. shap_values[0]) or a multi-row Explanation
-        object that we want to summarize.
+        A single row of a SHAP :class:`.Explanation` object (i.e. ``shap_values[0]``) or
+        a multi-row Explanation object that we want to summarize.
 
     max_display : int
-        The maximum number of bars to display.
+        How many top features to include in the bar plot (default is 10).
 
     show : bool
-        If show is set to False then we don't call the matplotlib.pyplot.show() function. This allows
-        further customization of the plot by the caller after the bar() function is finished.
+        Whether ``matplotlib.pyplot.show()`` is called before returning.
+        Setting this to ``False`` allows the plot
+        to be customized further after it has been created.
+
+    Examples
+    --------
+
+    See `bar plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/bar.html>`_.
 
     """
 

shap/plots/_beeswarm.py

@@ -34,17 +34,33 @@ def beeswarm(shap_values, max_display=10, order=Explanation.abs.mean(0),
     Parameters
     ----------
     shap_values : Explanation
-        This is an Explanation object containing a matrix of SHAP values (# samples x # features).
+        This is an :class:`.Explanation` object containing a matrix of SHAP values
+        (# samples x # features).
 
     max_display : int
-        How many top features to include in the plot (default is 20, or 7 for interaction plots)
+        How many top features to include in the plot (default is 10, or 7 for
+        interaction plots).
+
+    show : bool
+        Whether ``matplotlib.pyplot.show()`` is called before returning.
+        Setting this to ``False`` allows the plot
+        to be customized further after it has been created.
+
+    color_bar : bool
+        Whether to draw the color bar (legend).
 
     plot_size : "auto" (default), float, (float, float), or None
-        What size to make the plot. By default the size is auto-scaled based on the number of
-        features that are being displayed. Passing a single float will cause each row to be that
-        many inches high. Passing a pair of floats will scale the plot by that
-        number of inches. If None is passed then the size of the current figure will be left
-        unchanged.
+        What size to make the plot. By default, the size is auto-scaled based on the
+        number of features that are being displayed. Passing a single float will cause
+        each row to be that many inches high. Passing a pair of floats will scale the
+        plot by that number of inches. If ``None`` is passed, then the size of the
+        current figure will be left unchanged.
+
+    Examples
+    --------
+
+    See `beeswarm plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/beeswarm.html>`_.
+
     """
 
     if not isinstance(shap_values, Explanation):

shap/plots/_decision.py

@@ -244,29 +244,32 @@ def decision(
     ----------
     base_value : float or numpy.ndarray
         This is the reference value that the feature contributions start from. Usually, this is
-        explainer.expected_value.
+        ``explainer.expected_value``.
 
     shap_values : numpy.ndarray
-        Matrix of SHAP values (# features) or (# samples x # features) from explainer.shap_values(). Or cube of SHAP
-        interaction values (# samples x # features x # features) from explainer.shap_interaction_values().
+        Matrix of SHAP values (# features) or (# samples x # features) from
+        ``explainer.shap_values()``. Or cube of SHAP interaction values (# samples x
+        # features x # features) from ``explainer.shap_interaction_values()``.
 
     features : numpy.array or pandas.Series or pandas.DataFrame or numpy.ndarray or list
         Matrix of feature values (# features) or (# samples x # features). This provides the values of all the
         features and, optionally, the feature names.
 
     feature_names : list or numpy.ndarray
-        List of feature names (# features). If None, names may be derived from the features argument if a Pandas
-        object is provided. Otherwise, numeric feature names will be generated.
+        List of feature names (# features). If ``None``, names may be derived from the
+        ``features`` argument if a Pandas object is provided. Otherwise, numeric feature
+        names will be generated.
 
     feature_order : str or None or list or numpy.ndarray
-        Any of "importance" (the default), "hclust" (hierarchical clustering), "none", or a list/array of indices.
+        Any of "importance" (the default), "hclust" (hierarchical clustering), ``None``,
+        or a list/array of indices.
 
     feature_display_range: slice or range
-        The slice or range of features to plot after ordering features by feature_order. A step of 1 or None
+        The slice or range of features to plot after ordering features by ``feature_order``. A step of 1 or ``None``
         will display the features in ascending order. A step of -1 will display the features in descending order. If
-        feature_display_range=None, slice(-1, -21, -1) is used (i.e. show the last 20 features in descending order).
-        If shap_values contains interaction values, the number of features is automatically expanded to include all
-        possible interactions: N(N + 1)/2 where N = shap_values.shape[1].
+        ``feature_display_range=None``, ``slice(-1, -21, -1)`` is used (i.e. show the last 20 features in descending order).
+        If ``shap_values`` contains interaction values, the number of features is automatically expanded to include all
+        possible interactions: N(N + 1)/2 where N = ``shap_values.shape[1]``.
 
     highlight : Any
         Specify which observations to draw in a different line style. All numpy indexing methods are supported. For
@@ -277,7 +280,7 @@ def decision(
         log-odds into probabilities.
 
     plot_color : str or matplotlib.colors.ColorMap
-        Color spectrum used to draw the plot lines. If str, a registered matplotlib color name is assumed.
+        Color spectrum used to draw the plot lines. If ``str``, a registered matplotlib color name is assumed.
 
     axis_color : str or int
         Color used to draw plot axes.
@@ -289,39 +292,46 @@ def decision(
         Alpha blending value in [0, 1] used to draw plot lines.
 
     color_bar : bool
-        Whether to draw the color bar.
+        Whether to draw the color bar (legend).
 
     auto_size_plot : bool
-        Whether to automatically size the matplotlib plot to fit the number of features displayed. If `False`,
-        specify the plot size using matplotlib before calling this function.
+        Whether to automatically size the matplotlib plot to fit the number of features
+        displayed. If ``False``, specify the plot size using matplotlib before calling
+        this function.
 
     title : str
         Title of the plot.
 
     xlim: tuple[float, float]
-        The extents of the x-axis (e.g. (-1.0, 1.0)). If not specified, the limits are determined by the
-        maximum/minimum predictions centered around base_value when link='identity'. When link='logit', the
-        x-axis extents are (0, 1) centered at 0.5. x_lim values are not transformed by the link function. This
-        argument is provided to simplify producing multiple plots on the same scale for comparison.
+        The extents of the x-axis (e.g. ``(-1.0, 1.0)``). If not specified, the limits
+        are determined by the maximum/minimum predictions centered around base_value
+        when ``link="identity"``. When ``link="logit"``, the x-axis extents are ``(0,
+        1)`` centered at 0.5. ``xlim`` values are not transformed by the ``link``
+        function. This argument is provided to simplify producing multiple plots on the
+        same scale for comparison.
 
     show : bool
-        Whether to automatically display the plot.
+        Whether ``matplotlib.pyplot.show()`` is called before returning.
+        Setting this to ``False`` allows the plot
+        to be customized further after it has been created.
 
     return_objects : bool
-        Whether to return a DecisionPlotResult object containing various plotting features. This can be used to
-        generate multiple decision plots using the same feature ordering and scale.
+        Whether to return a :obj:`DecisionPlotResult` object containing various plotting
+        features. This can be used to generate multiple decision plots using the same
+        feature ordering and scale.
 
     ignore_warnings : bool
         Plotting many data points or too many features at a time may be slow, or may create very large plots. Set
-        this argument to `True` to override hard-coded limits that prevent plotting large amounts of data.
+        this argument to ``True`` to override hard-coded limits that prevent plotting large amounts of data.
 
     new_base_value : float
-        SHAP values are relative to a base value; by default, the expected value of the model's raw predictions. Use
-        `new_base_value` to shift the base value to an arbitrary value (e.g. the cutoff point for a binary
+        SHAP values are relative to a base value. By default, this base value is the
+        expected value of the model's raw predictions. Use ``new_base_value`` to shift
+        the base value to an arbitrary value (e.g. the cutoff point for a binary
         classification task).
 
     legend_labels : list of str
-        List of legend labels. If `None`, legend will not be shown.
+        List of legend labels. If ``None``, legend will not be shown.
 
     legend_location : str
         Legend location. Any of "best", "upper right", "upper left", "lower left", "lower right", "right",
@@ -330,15 +340,19 @@ def decision(
     Returns
     -------
     DecisionPlotResult or None
-        Returns a DecisionPlotResult object if `return_objects=True`. Returns `None` otherwise (the default).
+        Returns a :obj:`DecisionPlotResult` object if ``return_objects=True``. Returns ``None`` otherwise (the default).
+
+    Examples
+    --------
 
-    Example
-    -------
     Plot two decision plots using the same feature order and x-axis.
+
         >>> range1, range2 = range(20), range(20, 40)
         >>> r = decision_plot(base, shap_values[range1], features[range1], return_objects=True)
         >>> decision_plot(base, shap_values[range2], features[range2], feature_order=r.feature_idx, xlim=r.xlim)
 
+    See more `decision plot examples here <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/decision_plot.html>`_.
+
     """
 
     # code taken from force_plot. auto unwrap the base_value

shap/plots/_force.py

@@ -28,21 +28,22 @@
 def force(base_value, shap_values=None, features=None, feature_names=None, out_names=None, link="identity",
           plot_cmap="RdBu", matplotlib=False, show=True, figsize=(20,3), ordering_keys=None, ordering_keys_time_format=None,
           text_rotation=0, contribution_threshold=0.05):
-    """ Visualize the given SHAP values with an additive force layout.
+    """Visualize the given SHAP values with an additive force layout.
 
     Parameters
     ----------
     base_value : float
-        This is the reference value that the feature contributions start from. For SHAP values it should
-        be the value of explainer.expected_value.
+        This is the reference value that the feature contributions start from.
+        For SHAP values, it should be the value of ``explainer.expected_value``.
 
     shap_values : numpy.array
-        Matrix of SHAP values (# features) or (# samples x # features). If this is a 1D array then a single
-        force plot will be drawn, if it is a 2D array then a stacked force plot will be drawn.
+        Matrix of SHAP values (# features) or (# samples x # features). If this is a
+        1D array, then a single force plot will be drawn. If it is a 2D array, then a
+        stacked force plot will be drawn.
 
     features : numpy.array
         Matrix of feature values (# features) or (# samples x # features). This provides the values of all the
-        features, and should be the same shape as the shap_values argument.
+        features, and should be the same shape as the ``shap_values`` argument.
 
     feature_names : list
         List of feature names (# features).
@@ -51,12 +52,13 @@ def force(base_value, shap_values=None, features=None, feature_names=None, out_n
         The name of the output of the model (plural to support multi-output plotting in the future).
 
     link : "identity" or "logit"
-        The transformation used when drawing the tick mark labels. Using logit will change log-odds numbers
+        The transformation used when drawing the tick mark labels. Using "logit" will change log-odds numbers
         into probabilities.
 
     matplotlib : bool
-        Whether to use the default Javascript output, or the (less developed) matplotlib output. Using matplotlib
-        can be helpful in scenarios where rendering Javascript/HTML is inconvenient.
+        Whether to use the default Javascript output, or the (less developed) matplotlib output.
+        Using matplotlib can be helpful in scenarios where rendering Javascript/HTML
+        is inconvenient.
 
     contribution_threshold : float
         Controls the feature names/values that are displayed on force plot.
@@ -257,16 +259,18 @@ def save_html(out_file, plot, full_html=True):
     Parameters
     ----------
     out_file : str or file
-        Location or file to be written to
+        Location or file to be written to.
+
     plot : BaseVisualizer
-        Visualizer returned by shap.force_plot()
+        Visualizer returned by :func:`shap.plots.force()`.
+
     full_html : boolean (default: True)
-        If True, writes a complete HTML document starting
-        with an <html> tag. If False, only script and div
+        If ``True``, writes a complete HTML document starting
+        with an ``<html>`` tag. If ``False``, only script and div
         tags are included.
     """
 
-    assert isinstance(plot, BaseVisualizer), "save_html requires a Visualizer returned by shap.force_plot()."
+    assert isinstance(plot, BaseVisualizer), "`save_html` requires a Visualizer returned by `shap.plots.force()`."
     internal_open = False
     if type(out_file) == str:
         out_file = open(out_file, "w", encoding="utf-8")

shap/plots/_heatmap.py

@@ -14,37 +14,46 @@ def heatmap(shap_values, instance_order=Explanation.hclust(), feature_values=Exp
     """Create a heatmap plot of a set of SHAP values.
 
     This plot is designed to show the population substructure of a dataset using supervised
-    clustering and a heatmap. Supervised clustering involves clustering data points not by their original
-    feature values but by their explanations. By default we cluster using shap.utils.hclust_ordering
+    clustering and a heatmap.
+    Supervised clustering involves clustering data points not by their original
+    feature values but by their explanations.
+    By default, we cluster using :func:`shap.utils.hclust_ordering`,
     but any clustering can be used to order the samples.
 
     Parameters
     ----------
     shap_values : shap.Explanation
-        A multi-row Explanation object that we want to visualize in a cluster ordering.
+        A multi-row :class:`.Explanation` object that we want to visualize in a
+        cluster ordering.
 
     instance_order : OpChain or numpy.ndarray
         A function that returns a sort ordering given a matrix of SHAP values and an axis, or
-        a direct sample ordering given as an numpy.ndarray.
+        a direct sample ordering given as an ``numpy.ndarray``.
 
     feature_values : OpChain or numpy.ndarray
         A function that returns a global summary value for each input feature, or an array of such values.
 
     feature_order : None, OpChain, or numpy.ndarray
         A function that returns a sort ordering given a matrix of SHAP values and an axis, or
-        a direct input feature ordering given as an numpy.ndarray. If None then we use
-        feature_values.argsort
+        a direct input feature ordering given as an ``numpy.ndarray``.
+        If ``None``, then we use ``feature_values.argsort``.
 
     max_display : int
-        The maximum number of features to display.
+        The maximum number of features to display (default is 10).
 
     show : bool
-        If show is set to False then we don't call the matplotlib.pyplot.show() function. This allows
-        further customization of the plot by the caller after the bar() function is finished.
+        Whether ``matplotlib.pyplot.show()`` is called before returning.
+        Setting this to ``False`` allows the plot
+        to be customized further after it has been created.
 
     plot_width: int, default 8
         The width of the heatmap plot.
 
+    Examples
+    --------
+
+    See `heatmap plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/heatmap.html>`_.
+
     """
 
     # sort the SHAP values matrix by rows and columns