Plotting

Heatmap

graspologic.plot.heatmap(X, transform=None, figsize=(10, 10), title=None, context='talk', font_scale=1, xticklabels=False, yticklabels=False, cmap='RdBu_r', vmin=None, vmax=None, center=0, cbar=True, inner_hier_labels=None, outer_hier_labels=None, hier_label_fontsize=30, ax=None, title_pad=None, sort_nodes=False, **kwargs)

Plots a graph as a color-encoded matrix.

Nodes can be grouped by providing inner_hier_labels or both inner_hier_labels and outer_hier_labels. Nodes can also be sorted by the degree from largest to smallest degree nodes. The nodes will be sorted within each group if labels are also provided.

Read more in the Heatmap: Visualizing a Graph Tutorial

Parameters:

Xnx.Graph or np.ndarray object

Graph or numpy matrix to plot

transformNone, or string {'log', 'log10', 'zero-boost', 'simple-all', 'simple-nonzero'}

• 'log'

  Plots the natural log of all nonzero numbers

• 'log10'

  Plots the base 10 log of all nonzero numbers

• 'zero-boost'

  Pass to ranks method. preserves the edge weight for all 0s, but ranks the other edges as if the ranks of all 0 edges has been assigned.

• 'simple-all'

  Pass to ranks method. Assigns ranks to all non-zero edges, settling ties using the average. Ranks are then scaled by \(\frac{rank(\text{non-zero edges})}{n^2 + 1}\) where n is the number of nodes

• 'simple-nonzero'

  Pass to ranks method. Same as simple-all, but ranks are scaled by \(\frac{rank(\text{non-zero edges})}{\text{# non-zero edges} + 1}\)

• 'binarize'

  Binarize input graph such that any edge weight greater than 0 becomes 1.

figsizetuple of integers, optional, default: (10, 10)

Width, height in inches.

titlestr, optional, default: None

Title of plot.

contextNone, or one of {paper, notebook, talk (default), poster}

The name of a preconfigured set.

font_scalefloat, optional, default: 1

Separate scaling factor to independently scale the size of the font elements.

xticklabels, yticklabelsbool or list, optional

If list-like, plot these alternate labels as the ticklabels.

cmapstr, list of colors, or matplotlib.colors.Colormap, default: 'RdBu_r'

Valid matplotlib color map.

vmin, vmaxfloats, optional (default=None)

Values to anchor the colormap, otherwise they are inferred from the data and other keyword arguments.

centerfloat, default: 0

The value at which to center the colormap

cbarbool, default: True

Whether to draw a colorbar.

inner_hier_labelsarray-like, length of X's first dimension, default: None

Categorical labeling of the nodes. If not None, will group the nodes according to these labels and plot the labels on the marginal

outer_hier_labelsarray-like, length of X's first dimension, default: None

Categorical labeling of the nodes, ignored without inner_hier_labels If not None, will plot these labels as the second level of a hierarchy on the marginals

hier_label_fontsizeint

Size (in points) of the text labels for the inner_hier_labels and outer_hier_labels.

axmatplotlib Axes, optional

Axes in which to draw the plot, otherwise will generate its own axes

title_padint, float or None, optional (default=None)

Custom padding to use for the distance of the title from the heatmap. Autoscales if None

sort_nodesboolean, optional (default=False)

Whether or not to sort the nodes of the graph by the sum of edge weights (degree for an unweighted graph). If inner_hier_labels is passed and sort_nodes is True, will sort nodes this way within block.

**kwargsdict, optional

additional plotting arguments passed to Seaborn's heatmap

Parameters:

• X (ndarray | csr_array | Graph) --

• transform (str | None) --

• figsize (Tuple[int, int]) --

• title (str | None) --

• context (str) --

• font_scale (int) --

• xticklabels (bool) --

• yticklabels (bool) --

• cmap (str) --

• vmin (float | None) --

• vmax (float | None) --

• center (int) --

• cbar (bool) --

• inner_hier_labels (ndarray | List[Any] | None) --

• outer_hier_labels (ndarray | List[Any] | None) --

• hier_label_fontsize (int) --

• ax (Axes | None) --

• title_pad (float | None) --

• sort_nodes (bool) --

• kwargs (Any) --

Return type:

Axes

Gridplot

graspologic.plot.gridplot(X, labels=None, transform=None, height=10, title=None, context='talk', font_scale=1, alpha=0.7, sizes=(10, 200), palette='Set1', legend_name='Type', inner_hier_labels=None, outer_hier_labels=None, hier_label_fontsize=30, title_pad=None, sort_nodes=False)

Plots multiple graphs on top of each other with dots as edges.

This function is useful for visualizing multiple graphs simultaneously. The size of the dots correspond to the edge weights of the graphs, and colors represent input graphs.

Read more in the Gridplot: Visualize Multiple Graphs Tutorial

Parameters:

Xlist of nx.Graph or np.ndarray object

List of nx.Graph or numpy arrays to plot

labelslist of str

List of strings, which are labels for each element in X. len(X) == len(labels).

transformNone, or string {'log', 'log10', 'zero-boost', 'simple-all', 'simple-nonzero'}

• 'log'

  Plots the natural log of all nonzero numbers

• 'log10'

  Plots the base 10 log of all nonzero numbers

• 'zero-boost'

  Pass to ranks method. preserves the edge weight for all 0s, but ranks the other edges as if the ranks of all 0 edges has been assigned.

• 'simple-all'

  Pass to ranks method. Assigns ranks to all non-zero edges, settling ties using the average. Ranks are then scaled by \(\frac{rank(\text{non-zero edges})}{n^2 + 1}\) where n is the number of nodes

• 'simple-nonzero'

  Pass to ranks method. Same as simple-all, but ranks are scaled by \(\frac{rank(\text{non-zero edges})}{\text{# non-zero edges} + 1}\)

• 'binarize'

  Binarize input graph such that any edge weight greater than 0 becomes 1.

heightint, optional, default: 10

Height of figure in inches.

titlestr, optional, default: None

Title of plot.

contextNone, or one of {paper, notebook, talk (default), poster}

The name of a preconfigured set.

font_scalefloat, optional, default: 1

Separate scaling factor to independently scale the size of the font elements.

palettestr, dict, optional, default: 'Set1'

Set of colors for mapping the hue variable. If a dict, keys should be values in the hue variable. For acceptable string arguments, see the palette options at Choosing Colormaps in Matplotlib

alphafloat [0, 1], default0.7

Alpha value of plotted gridplot points

sizeslength 2 tuple, default: (10, 200)

Min and max size to plot edge weights

legend_namestring, default: 'Type'

Name to plot above the legend

inner_hier_labelsarray-like, length of X's first dimension, default: None

Categorical labeling of the nodes. If not None, will group the nodes according to these labels and plot the labels on the marginal

outer_hier_labelsarray-like, length of X's first dimension, default: None

Categorical labeling of the nodes, ignored without inner_hier_labels If not None, will plot these labels as the second level of a hierarchy on the marginals

hier_label_fontsizeint

Size (in points) of the text labels for the inner_hier_labels and outer_hier_labels.

title_padint, float or None, optional (default=None)

Custom padding to use for the distance of the title from the heatmap. Autoscales if None

sort_nodesboolean, optional (default=False)

Whether or not to sort the nodes of the graph by the sum of edge weights (degree for an unweighted graph). If inner_hier_labels is passed and sort_nodes is True, will sort nodes this way within block.

Parameters:

• X (ndarray | csr_array | Graph) --

• labels (List[str] | None) --

• transform (str | None) --

• height (int) --

• title (str | None) --

• context (str) --

• font_scale (float) --

• alpha (float) --

• sizes (Tuple[int, int]) --

• palette (str) --

• legend_name (str) --

• inner_hier_labels (ndarray | List[Any] | None) --

• outer_hier_labels (ndarray | List[Any] | None) --

• hier_label_fontsize (int) --

• title_pad (float | None) --

• sort_nodes (bool) --

Return type:

Axes

Pairplot

graspologic.plot.pairplot(X, labels=None, col_names=None, title=None, legend_name=None, variables=None, height=2.5, context='talk', font_scale=1, palette='Set1', alpha=0.7, size=50, marker='.', diag_kind='auto')

Plot pairwise relationships in a dataset.

By default, this function will create a grid of axes such that each dimension in data will by shared in the y-axis across a single row and in the x-axis across a single column.

The off-diagonal axes show the pairwise relationships displayed as scatterplot. The diagonal axes show the univariate distribution of the data for that dimension displayed as either a histogram or kernel density estimates (KDEs).

Read more in the Pairplot: Visualizing High Dimensional Data Tutorial

Parameters:

Xarray-like, shape (n_samples, n_features)

Input data.

labelsarray-like or list, shape (n_samples), optional

Labels that correspond to each sample in X.

col_namesarray-like or list, shape (n_features), optional

Names or labels for each feature in X. If not provided, the default will be Dimension 1, Dimension 2, etc.

titlestr, optional, default: None

Title of plot.

legend_namestr, optional, default: None

Title of the legend.

variableslist of variable names, optional

Variables to plot based on col_names, otherwise use every column with a numeric datatype.

heightint, optional, default: 10

Height of figure in inches.

contextNone, or one of {paper, notebook, talk (default), poster}

The name of a preconfigured set.

font_scalefloat, optional, default: 1

Separate scaling factor to independently scale the size of the font elements.

palettestr, dict, optional, default: 'Set1'

Set of colors for mapping the hue variable. If a dict, keys should be values in the hue variable. For acceptable string arguments, see the palette options at Choosing Colormaps in Matplotlib.

alphafloat, optional, default: 0.7

Opacity value of plotter markers between 0 and 1

sizefloat or int, optional, default: 50

Size of plotted markers.

markerstring, optional, default: '.'

Matplotlib marker specifier, see the marker options at Matplotlib style marker specification

Parameters:

• X (ndarray) --

• labels (ndarray | List[Any] | None) --

• col_names (ndarray | List[Any] | None) --

• title (str | None) --

• legend_name (str | None) --

• variables (List[str] | None) --

• height (float) --

• context (str) --

• font_scale (float) --

• palette (str) --

• alpha (float) --

• size (float) --

• marker (str) --

• diag_kind (str) --

Return type:

PairGrid

graspologic.plot.pairplot_with_gmm(X, gmm, labels=None, cluster_palette='Set1', label_palette='Set1', title=None, legend_name=None, context='talk', font_scale=1, alpha=0.7, figsize=(12, 12), histplot_kws=None)

Plot pairwise relationships in a dataset, also showing a clustering predicted by a Gaussian mixture model.

By default, this function will create a grid of axes such that each dimension in data will by shared in the y-axis across a single row and in the x-axis across a single column.

The off-diagonal axes show the pairwise relationships displayed as scatterplot. The diagonal axes show the univariate distribution of the data for that dimension displayed as either a histogram or kernel density estimates (KDEs).

Read more in the Pairplot with GMM: Visualizing High Dimensional Data and Clustering Tutorial

Parameters:

Xarray-like, shape (n_samples, n_features)

Input data.

gmm: GaussianMixture object

A fit sklearn.mixture.GaussianMixture object. Gaussian mixture models (GMMs) are probabilistic models for representing data based on normally distributed subpopulations, GMM clusters each data point into a corresponding subpopulation.

labelsarray-like or list, shape (n_samples), optional

Labels that correspond to each sample in X. If labels are not passed in then labels are predicted by gmm.

label_palettestr or dict, optional, default: 'Set1'

Palette used to color points if labels are passed in.

cluster_palettestr or dict, optional, default: 'Set1'

Palette used to color GMM ellipses (and points if no labels are passed).

titlestring, default: ""

Title of the plot.

legend_namestring, default: None

Name to put above the legend. If None, will be "Cluster" if no custom labels are passed, and "" otherwise.

contextNone, or one of {talk (default), paper, notebook, poster}

Seaborn plotting context

font_scalefloat, optional, default: 1

Separate scaling factor to independently scale the size of the font elements.

alphafloat, optional, default: 0.7

Opacity value of plotter markers between 0 and 1

figsizetuple

The size of the 2d subplots configuration

histplot_kwsdict, default: {}

Keyword arguments passed down to seaborn.histplot()

Returns:

figmatplotlib Figure

axesnp.ndarray

Array of matplotlib Axes

Parameters:

• X (ndarray) --

• gmm (GaussianMixture) --

• labels (ndarray | List[Any] | None) --

• cluster_palette (str | Dict) --

• label_palette (str | Dict) --

• title (str | None) --

• legend_name (str | None) --

• context (str) --

• font_scale (float) --

• alpha (float) --

• figsize (Tuple[int, int]) --

• histplot_kws (Dict[str, Any] | None) --

Return type:

Tuple[Figure, Axes]

See also

graspologic.plot.pairplot

graspologic.cluster.AutoGMMCluster

sklearn.mixture.GaussianMixture

Degreeplot

graspologic.plot.degreeplot(X, labels=None, direction='out', title='Degree plot', context='talk', font_scale=1, figsize=(10, 5), palette='Set1')

Plots the distribution of node degrees for the input graph. Allows for sets of node labels, will plot a distribution for each node category.

Parameters:

Xnp.ndarray (2D)

input graph

labels1d np.ndarray or list, same length as dimensions of X

Labels for different categories of graph nodes

directionstring, ('out', 'in')

Whether to plot out degree or in degree for a directed graph

titlestring, default'Degree plot'

Plot title

contextNone, or one of {talk (default), paper, notebook, poster}

Seaborn plotting context

font_scalefloat, optional, default: 1

Separate scaling factor to independently scale the size of the font elements.

palettestr, dict, optional, default: 'Set1'

Set of colors for mapping the hue variable. If a dict, keys should be values in the hue variable. For acceptable string arguments, see the palette options at Choosing Colormaps in Matplotlib.

figsizetuple of length 2, default (10, 5)

Size of the figure (width, height)

Returns:

axmatplotlib axis object

Output plot

Parameters:

• X (ndarray) --

• labels (ndarray | List[Any] | None) --

• direction (str) --

• title (str) --

• context (str) --

• font_scale (float) --

• figsize (Tuple[int, int]) --

• palette (str) --

Return type:

Axes

Edgeplot

graspologic.plot.edgeplot(X, labels=None, nonzero=False, title='Edge plot', context='talk', font_scale=1, figsize=(10, 5), palette='Set1')

Plots the distribution of edge weights for the input graph. Allows for sets of node labels, will plot edge weight distribution for each node category.

Parameters:

Xnp.ndarray (2D)

Input graph

labels1d np.ndarray or list, same length as dimensions of X

Labels for different categories of graph nodes

nonzeroboolean, default: False

Whether to restrict the edgeplot to only the non-zero edges

titlestring, default'Edge plot'

Plot title

contextNone, or one of {talk (default), paper, notebook, poster}

Seaborn plotting context

font_scalefloat, optional, default: 1

Separate scaling factor to independently scale the size of the font elements.

palettestr, dict, optional, default: 'Set1'

Set of colors for mapping the hue variable. If a dict, keys should be values in the hue variable. For acceptable string arguments, see the palette options at Choosing Colormaps in Matplotlib.

figsizetuple of length 2, default (10, 5)

Size of the figure (width, height)

Returns:

axmatplotlib axis object

Output plot

Parameters:

• X (ndarray) --

• labels (ndarray | List[Any] | None) --

• nonzero (bool) --

• title (str) --

• context (str) --

• font_scale (float) --

• figsize (Tuple[int, int]) --

• palette (str) --

Return type:

Axes

Screeplot

graspologic.plot.screeplot(X, title='Scree plot', context='talk', font_scale=1, figsize=(10, 5), ax=None, cumulative=True, show_first=None, show_elbow=False)

Plots the distribution of singular values for a matrix, either showing the raw distribution or an empirical CDF (depending on cumulative)

Parameters:

Xnp.ndarray (2D)

Input matrix

titlestring, default'Scree plot'

Plot title

contextNone, or one of {talk (default), paper, notebook, poster}

Seaborn plotting context

font_scalefloat, optional, default: 1

Separate scaling factor to independently scale the size of the font elements.

figsizetuple of length 2, default (10, 5)

Size of the figure (width, height)

cumulativeboolean, default: True

Whether or not to plot a cumulative cdf of singular values

show_firstint or None, default: None

Whether to restrict the plot to the first show_first components

show_elbowbool, or int, default: False

Whether to show an elbow (an optimal embedding dimension) estimated via [1]. An integer is interpreted as a number of likelihood elbows to return. Must be > 1.

Returns:

axmatplotlib axis object

Output plot

Parameters:

• X (ndarray) --

• title (str) --

• context (str) --

• font_scale (float) --

• figsize (Tuple[int, int]) --

• ax (Axes | None) --

• cumulative (bool) --

• show_first (int | None) --

• show_elbow (bool | int | None) --

Return type:

Axes

References

[1]

Zhu, M. and Ghodsi, A. (2006). Automatic dimensionality selection from the scree plot via the use of profile likelihood. Computational Statistics & Data Analysis, 51(2), pp.918-930.

Adjplot

graspologic.plot.adjplot(data, ax=None, meta=None, plot_type='heatmap', group=None, group_order='size', item_order=None, color=None, highlight=None, palette='tab10', ticks=True, tick_pad=None, color_pad=None, border=True, center=0, cmap='RdBu_r', sizes=(5, 10), square=True, gridline_kws=None, spinestyle_kws=None, highlight_kws=None, **kws)

Sorts and plots a square matrix in various ways, and with optional information added to the margin of the matrix plot.

This function is a wrapper around matrixplot which assumes that the plotted matrix is square, and that the rows and columns represent the same items and have the same metadata (e.g. the adjacency matrix of a graph).

Read more in the Tutorial https://microsoft.github.io/graspologic/tutorials/plotting/matrixplot.html

Parameters:

datanp.ndarray or scipy.sparse.csr_array with ndim=2

Matrix to plot, must be square. Sparse matrix input is only accepted if plot_type == 'scattermap'.

axmatplotlib axes object (default=None)

Axes in which to draw the plot. If no axis is passed, one will be created.

plot_typestr in {"heatmap", "scattermap"} (default="heatmap")

"heatmap" will draw the matrix using seaborn.heatmap(), "scattermap" will draw each nonzero element of the matrix using seaborn.scatterplot(). "scattermap" is recommended for larger sparse matrices.

metapd.DataFrame or None, (default=None)

Metadata of the matrix.

• meta is pd.DataFrame

  All sorting keywords should only be str or list of str. They should contain references to columns in meta.

• meta is None

  All sorting keywords should only array-like with the same length as the corresponding axis of data.

groupstr, list of str, or array-like, (default=None)

Attribute(s) by which to group rows/columns of data. If multiple groups are specified, rows/columns will be sorted hierarchically (first by the first group), then within that group by a possible second group, etc.). Behaves similarly to pandas.DataFrame.sort_values().

group_orderstr, list of str, or array-like, (default="size")

Attribute(s) by which to sort the groups if provided by group. Groups are sorted by the mean of this attribute in ascending order. "size" is a special keyword which will sort groups by the number of elements per group.

item_orderstr, list of str, or array-like (default=None)

Attribute(s) by which to sort the individual rows/columns within each group.

colorstr, list of str, or array-like (default=None)

Attribute(s) to use for drawing colors on the borders of the matrix plot.

highlightstr, list of str, or array-like (default=None)

Attribute(s) in meta by which to draw highlighted separators between specific groups, can be useful for emphasizing a particular region of the plot. Styling of the highlighted separators can be specified via spinestyle_kws.

palettestr, dict, list of str or dict (default="tab10")

Colormap(s) of the color axes if specified by color.

ticksbool, optional (default=True)

Whether the plot has labels for the groups specified by group.

tick_padint or float (default=None)

Custom padding to use for the distance between tick axes

color_padint or float (default=None)

Custom padding to use for the distance between color axes

borderbool (default=True)

Whether the plot should have a border.

centerint (default=0)

The value at which to center the colormap when plotting divergent data (only used when plot_type="heatmap").

cmapstr (default="RdBu_r")

Colormap of the heatmap (only used when plot_type="heatmap").

sizestuple (default=(5, 10))

Min and max sizes of dots (only used when plot_type="scattermap").

squarebool (default=False)

Whether the plot should be square.

gridline_kwsdict (default=None)

Plotting arguments for the separators.

spinestyle_kwsdict (default=None)

Plotting arguments for the spine border.

highlight_kwsdict (default=None)

Plotting arguments for the highlighted separators.

**kwargs

Additional plotting arguments passed down to the plotting function which will draw the matrix data, see plot_type for more information.

Returns:

axmatplotlib axes object

Axes in which to draw the plot, by default None

dividerAxesLocator

Divider used to add new axes to the plot

Matrixplot

graspologic.plot.matrixplot(data, ax=None, col_meta=None, row_meta=None, plot_type='heatmap', col_group=None, row_group=None, col_group_order='size', row_group_order='size', col_item_order=None, row_item_order=None, col_color=None, row_color=None, col_highlight=None, row_highlight=None, col_palette='tab10', row_palette='tab10', col_ticks=True, row_ticks=True, col_tick_pad=None, row_tick_pad=None, col_color_pad=None, row_color_pad=None, border=True, center=0, cmap='RdBu_r', sizes=(5, 10), square=True, gridline_kws=None, spinestyle_kws=None, highlight_kws=None, **kws)

Sorts and plots a matrix in various ways, and with optional information added to the margin of the matrix plot.

Read more in the Tutorial https://microsoft.github.io/graspologic/tutorials/plotting/matrixplot.html

Parameters:

datanp.ndarray or scipy.sparse.csr_array with ndim=2

Matrix to plot. Sparse matrix input is only accepted if plot_type == 'scattermap'.

axmatplotlib axes object (default=None)

Axes in which to draw the plot. If no axis is passed, one will be created.

plot_typestr in {"heatmap", "scattermap"} (default="heatmap")

"heatmap" will draw the matrix using seaborn.heatmap(), "scattermap" will draw each nonzero element of the matrix using seaborn.scatterplot(). "scattermap" is recommended for larger sparse matrices.

{row,col}_metapd.DataFrame or None, (default=None)

Metadata of the matrix.

• {row,col}_meta is pd.DataFrame

  All sorting keywords should only be str or list of str. They should contain references to columns in meta.

• {row,col}_meta is None

  All sorting keywords should only array-like with the same length as the corresponding axis of data.

{row,col}_groupstr, list of str, or array-like, (default=None)

Attribute(s) by which to group rows/columns of data. If multiple groups are specified, rows/columns will be sorted hierarchically (first by the first group), then within that group by a possible second group, etc.). Behaves similarly to pandas.DataFrame.sort_values().

{row,col}_group_orderstr, list of str, or array-like, (default="size")

Attribute(s) by which to sort the groups if provided by {row,col}_group. Groups are sorted by the mean of this attribute in ascending order. "size" is a special keyword which will sort groups by the number of elements per group.

{row,col}_item_orderstr, list of str, or array-like (default=None)

Attribute(s) by which to sort the individual rows/columns within each group.

{row,col}_colorstr, list of str, or array-like (default=None)

Attribute(s) to use for drawing colors on the borders of the matrix plot.

{row,col}_highlightstr, list of str, or array-like (default=None)

Attribute(s) in meta by which to draw highlighted separators between specific groups, can be useful for emphasizing a particular region of the plot. Styling of the highlighted separators can be specified via spinestyle_kws.

{row,col}_palettestr, dict, list of str or dict (default="tab10")

Colormap(s) of the color axes if specified by {row,col}_color.

{row,col}_ticksbool, optional (default=True)

Whether the plot has labels for the groups specified by {row,col}_group.

{row,col}_tick_padint or float (default=None)

Custom padding to use for the distance between tick axes

{row,col}_color_padint or float (default=None)

Custom padding to use for the distance between color axes

borderbool (default=True)

Whether the plot should have a border.

centerint (default=0)

The value at which to center the colormap when plotting divergent data (only used when plot_type="heatmap").

cmapstr (default="RdBu_r")

Colormap of the heatmap (only used when plot_type="heatmap").

sizestuple (default=(5, 10))

Min and max sizes of dots (only used when plot_type="scattermap").

squarebool (default=False)

Whether the plot should be square.

gridline_kwsdict (default=None)

Plotting arguments for the separators.

spinestyle_kwsdict (default=None)

Plotting arguments for the spine border.

highlight_kwsdict (default=None)

Plotting arguments for the highlighted separators.

**kwargs

Additional plotting arguments passed down to the plotting function which will draw the matrix data, see plot_type for more information.

Returns:

axmatplotlib axes object

Axes in which to draw the plot, by default None

dividerAxesLocator

Divider used to add new axes to the plot