From 0c2a4dd12590af066a57b4d7796ca863b69917f5 Mon Sep 17 00:00:00 2001 From: Maoz Gelbart <13831112+MaozGelbart@users.noreply.github.com> Date: Tue, 11 Aug 2020 00:52:27 +0300 Subject: [PATCH] Improve matrix functions docstrings (#2188) * fix matplotlib backends usage path * add intersphinx links * Better comply with numpydoc --- doc/installing.rst | 2 +- seaborn/matrix.py | 46 +++++++++++++++++++++------------------------- 2 files changed, 22 insertions(+), 26 deletions(-) diff --git a/doc/installing.rst b/doc/installing.rst index ad7e7a5dfe..584d8331ea 100644 --- a/doc/installing.rst +++ b/doc/installing.rst @@ -56,7 +56,7 @@ include a reproducible example on synthetic data or one of the example datasets (accessed through :func:`load_dataset`). It is difficult to debug any issues without knowing the versions of seaborn and matplotlib you are using, as well as what `matplotlib backend -`__ you are have active, so please include those in your bug report. +`__ you are have active, so please include those in your bug report. .. raw:: html diff --git a/seaborn/matrix.py b/seaborn/matrix.py index fdfd4b0b80..a888eb5089 100644 --- a/seaborn/matrix.py +++ b/seaborn/matrix.py @@ -389,22 +389,23 @@ def heatmap( If True, write the data value in each cell. If an array-like with the same shape as ``data``, then use this to annotate the heatmap instead of the data. Note that DataFrames will match on position, not index. - fmt : string, optional + fmt : str, optional String formatting code to use when adding annotations. annot_kws : dict of key, value mappings, optional - Keyword arguments for ``ax.text`` when ``annot`` is True. + Keyword arguments for :meth:`matplotlib.axes.Axes.text` when ``annot`` + is True. linewidths : float, optional Width of the lines that will divide each cell. linecolor : color, optional Color of the lines that will divide each cell. - cbar : boolean, optional + cbar : bool, optional Whether to draw a colorbar. cbar_kws : dict of key, value mappings, optional - Keyword arguments for `fig.colorbar`. + Keyword arguments for :meth:`matplotlib.figure.Figure.colorbar`. cbar_ax : matplotlib Axes, optional Axes in which to draw the colorbar, otherwise take space from the main Axes. - square : boolean, optional + square : bool, optional If True, set the Axes aspect to "equal" so each cell will be square-shaped. xticklabels, yticklabels : "auto", bool, list-like, or int, optional @@ -412,7 +413,7 @@ def heatmap( the column names. If list-like, plot these alternate labels as the xticklabels. If an integer, use the column names but plot only every n label. If "auto", try to densely plot non-overlapping labels. - mask : boolean array or DataFrame, optional + mask : bool array or DataFrame, optional If passed, data will not be shown in cells where ``mask`` is True. Cells with missing values are automatically masked. ax : matplotlib Axes, optional @@ -420,14 +421,14 @@ def heatmap( Axes. kwargs : other keyword arguments All other keyword arguments are passed to - :func:`matplotlib.axes.Axes.pcolormesh`. + :meth:`matplotlib.axes.Axes.pcolormesh`. Returns ------- ax : matplotlib Axes Axes object with the heatmap. - See also + See Also -------- clustermap : Plot a matrix using hierachical clustering to arrange the rows and columns. @@ -534,8 +535,6 @@ def heatmap( >>> with sns.axes_style("white"): ... f, ax = plt.subplots(figsize=(7, 5)) ... ax = sns.heatmap(corr, mask=mask, vmax=.3, square=True) - - """ # Initialize the plotter object plotter = _HeatMapper(data, vmin, vmax, cmap, center, robust, annot, fmt, @@ -1246,19 +1245,18 @@ def clustermap( Parameters ---------- - data: 2D array-like + data : 2D array-like Rectangular data for clustering. Cannot contain NAs. pivot_kws : dict, optional If `data` is a tidy dataframe, can provide keyword arguments for pivot to create a rectangular dataframe. method : str, optional - Linkage method to use for calculating clusters. - See scipy.cluster.hierarchy.linkage documentation for more information: - https://docs.scipy.org/doc/scipy/reference/generated/scipy.cluster.hierarchy.linkage.html + Linkage method to use for calculating clusters. See + :func:`scipy.cluster.hierarchy.linkage` documentation for more + information. metric : str, optional Distance metric to use for the data. See - scipy.spatial.distance.pdist documentation for more options - https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.distance.pdist.html + :func:`scipy.spatial.distance.pdist` documentation for more options. To use different metrics (or methods) for rows and columns, you may construct each linkage matrix yourself and provide them as {row,col}_linkage. @@ -1272,10 +1270,10 @@ def clustermap( Either 0 (rows) or 1 (columns). Whether or not to standardize that dimension, meaning for each row or column, subtract the minimum and divide each by its maximum. - figsize: (width, height), optional + figsize : (width, height), optional Overall size of the figure. cbar_kws : dict, optional - Keyword arguments to pass to ``cbar_kws`` in ``heatmap``, e.g. to + Keyword arguments to pass to ``cbar_kws`` in :func:`heatmap`, e.g. to add a label to the colorbar. {row,col}_cluster : bool, optional If True, cluster the {rows, columns}. @@ -1290,11 +1288,11 @@ def clustermap( from the DataFrames column names or from the name of the Series. DataFrame/Series colors are also matched to the data by their index, ensuring colors are drawn in the correct order. - mask : boolean array or DataFrame, optional + mask : bool array or DataFrame, optional If passed, data will not be shown in cells where ``mask`` is True. Cells with missing values are automatically masked. Only used for visualizing, not for calculating. - {dendrogram,colors}_ratio: float, or pair of floats, optional + {dendrogram,colors}_ratio : float, or pair of floats, optional Proportion of the figure size devoted to the two marginal elements. If a pair is given, they correspond to (row, col) ratios. cbar_pos : (left, bottom, width, height), optional @@ -1304,12 +1302,12 @@ def clustermap( Parameters for the :class:`matplotlib.collections.LineCollection` that is used to plot the lines of the dendrogram tree. kwargs : other keyword arguments - All other keyword arguments are passed to :func:`heatmap` + All other keyword arguments are passed to :func:`heatmap`. Returns ------- - clustergrid : ClusterGrid - A ClusterGrid instance. + clustergrid : :class:`ClusterGrid` + A :class:`ClusterGrid` instance. Notes ----- @@ -1389,8 +1387,6 @@ def clustermap( :context: close-figs >>> g = sns.clustermap(iris, z_score=0, cmap="vlag") - - """ plotter = ClusterGrid(data, pivot_kws=pivot_kws, figsize=figsize, row_colors=row_colors, col_colors=col_colors,