Matplotlib#

matplotlib-backend visualizations in hiveplotlib.

hiveplotlib.viz.matplotlib.axes_viz(instance: BaseHivePlot | HivePlot | P2CP, fig: Figure | None = None, ax: Axes | None = None, buffer: float = 0.1, show_axes_labels: bool = True, axes_labels_buffer: float = 1.1, axes_labels_fontsize: int = 16, figsize: Tuple[float, float] = (10, 10), center_plot: bool = True, axes_off: bool = True, fig_kwargs: dict | None = None, text_kwargs: dict | None = None, **axes_kwargs) → Tuple[Figure, Axes]#

matplotlib visualization of axes in a HivePlot or P2CP instance.

Parameters:

instance – HivePlot or P2CP instance for which we want to draw axes.
fig – default None builds new figure. If a figure is specified, axes will be drawn on that figure. Note: fig and ax must BOTH be None to instantiate new figure and axes.
ax – default None builds new axis. If an axis is specified, Axis instances will be drawn on that axis. Note: fig and ax must BOTH be None to instantiate new figure and axes.
buffer – fraction of the axes past which to buffer x and y dimensions (e.g. setting buffer to 0.1 will find the maximum radius spanned by any Axis instance and set the x and y bounds as (-max_radius - buffer * max_radius, max_radius + buffer * max_radius)).
show_axes_labels – whether to label the hive plot axes in the figure (uses Axis.long_name for each Axis.)
axes_labels_buffer – fraction which to radially buffer axes labels (e.g. setting axes_label_buffer to 1.1 will be 10% further past the end of the axis moving from the origin of the plot).
axes_labels_fontsize – font size for axes labels.
figsize – size of figure. Note: only works if instantiating new figure and axes (e.g. fig and ax are None).
center_plot – whether to center the figure on (0, 0), the currently fixed center that the axes are drawn around by default. Will only run if there is at least one axis in instance.
axes_off – whether to turn off Cartesian x, y axes in resulting matplotlib figure (default True hides the x and y axes).
fig_kwargs – additional values to be called in plt.subplots() call. Note if figsize is added here, then it will be prioritized over the figsize parameter.
text_kwargs – additional kwargs passed to plt.text() call.
axes_kwargs – additional params that will be applied to all hive plot axes. Note, these are kwargs that affect a plt.plot() call.

Returns:

matplotlib figure, axis.

hiveplotlib.viz.matplotlib.edge_viz(instance: BaseHivePlot | HivePlot | P2CP, fig: Figure | None = None, ax: Axes | None = None, tags: Hashable | List[Hashable] | None = None, figsize: Tuple[float, float] = (10, 10), center_plot: bool = True, buffer: float = 0.1, axes_off: bool = True, fig_kwargs: dict | None = None, prioritize_array_over_color: bool = True, **edge_kwargs) → Tuple[Figure, Axes] | None#

matplotlib visualization of constructed edges in a HivePlot or P2CP instance.

Note

If instance is a HivePlot, then users can provide edge-specific data to plotting keyword arguments by providing column names from the HivePlot.edges.data DataFrame as values to one of the following options:

HivePlot.edge_plotting_keyword_arguments attribute via HivePlot.update_edge_plotting_keyword_arguments().
HivePlot.edges.edge_viz_kwargs attribute via HivePlot.edges.update_edge_viz_kwargs().
In this call in the provided edge_kwargs.

If instance is a HivePlot, then edge keyword arguments will be prioritized according to the following hierarchy:

The most prioritized arguments are the arguments stored in the hive plot hive_plot_edges attribute, followed by the provided edge_kwargs, then the edge keyword argument hierarchy set by the hive plot’s edge_kwarg_hierarchy attribute, and finally the HivePlot.edges.edge_viz_kwargs.

If any keyword arguments in the hive_plot_edges attribute are also provided in this function’s edge_kwargs, then a warning will be raised.

Parameters:

instance – HivePlot or P2CP instance for which we want to draw edges.
fig – default None builds new figure. If a figure is specified, edges will be drawn on that figure. Note: fig and ax must BOTH be None to instantiate new figure and axes.
ax – default None builds new axis. If an axis is specified, edges will be drawn on that axis. Note: fig and ax must BOTH be None to instantiate new figure and axes.
tags – which tag(s) of data to plot. Default None plots all tags of data. Can supply either a single tag or list of tags.
figsize – size of figure. Note: only works if instantiating new figure and axes (e.g. fig and ax are None).
center_plot – whether to center the figure on (0, 0), the currently fixed center that the axes are drawn around by default. Will only run if there is at least one axis in instance.
buffer – fraction of the axes past which to buffer x and y dimensions (e.g. setting buffer to 0.1 will find the maximum radius spanned by any Axis instance and set the x and y bounds as (-max_radius - buffer * max_radius, max_radius + buffer * max_radius)).
axes_off – whether to turn off Cartesian x, y axes in resulting matplotlib figure (default True hides the x and y axes).
fig_kwargs – additional values to be called in plt.subplots() call. Note if figsize is added here, then it will be prioritized over the figsize parameter.
prioritize_array_over_color – if both array and color are provided by the user as edge kwargs for any subset of edges, then setting this to True will drop color and use array to color edges. If False, will instead use color. Default True.
edge_kwargs – additional params that will be applied to all edges on all axes (but kwargs specified beforehand in hiveplotlib.BaseHivePlot.connect_axes() / hiveplotlib.P2CP.build_edges() or hiveplotlib.BaseHivePlot.add_edge_kwargs() / hiveplotlib.P2CP.add_edge_kwargs() will take priority). To overwrite previously set kwargs, see hiveplotlib.BaseHivePlot.add_edge_kwargs() / hiveplotlib.P2CP.add_edge_kwargs() for more. Note, these are kwargs that affect a matplotlib.collections.LineCollection() call. Edge data values can also be used, see note above for more details.

Returns:

matplotlib figure, axis. If instance cannot be plotted with this function, returns None.

hiveplotlib.viz.matplotlib.hive_plot_viz(hive_plot: BaseHivePlot | HivePlot, fig: Figure | None = None, ax: Axes | None = None, tags: Hashable | List[Hashable] | None = None, figsize: Tuple[float, float] = (10, 10), center_plot: bool = True, buffer: float = 0.1, show_axes_labels: bool = True, axes_labels_buffer: float = 1.1, axes_labels_fontsize: int = 16, axes_off: bool = True, node_kwargs: dict | None = None, axes_kwargs: dict | None = None, text_kwargs: dict | None = None, fig_kwargs: dict | None = None, prioritize_array_over_color: bool = True, **edge_kwargs) → Tuple[Figure, Axes]#

matplotlib visualization of a HivePlot instance.

Note

Users can provide node-specific data to plotting keyword arguments by providing column names from the HivePlot.nodes.data DataFrame as values in either the HivePlot.nodes.node_viz_kwargs dictionary via HivePlot.update_node_viz_kwargs() or in this call in the provided node_kwargs.

Any provided node plotting keyword arguments in HivePlot.nodes.node_viz_kwargs will be prioritized over any provided node_kwargs.

Users can provide edge-specific data to plotting keyword arguments by providing column names from the HivePlot.edges.data DataFrame as values to one of the following options:

HivePlot.edge_plotting_keyword_arguments attribute via HivePlot.update_edge_plotting_keyword_arguments().
HivePlot.edges.edge_viz_kwargs attribute via HivePlot.edges.update_edge_viz_kwargs().
In this call in the provided edge_kwargs.

Edge keyword arguments will be prioritized according to the following hierarchy:

If any keyword arguments in the hive_plot_edges attribute are also provided in this function’s edge_kwargs, then a warning will be raised.

Parameters:

hive_plot – HivePlot instance we want to visualize.
fig – default None builds new figure. If a figure is specified, hive plot will be drawn on that figure. Note: fig and ax must BOTH be None to instantiate new figure and axes.
ax – default None builds new axis. If an axis is specified, hive plot will be drawn on that axis. Note: fig and ax must BOTH be None to instantiate new figure and axes.
tags – which tag(s) of data to plot. Default None plots all tags of data. Can supply either a single tag or list of tags.
figsize – size of figure. Note: only works if instantiating new figure and axes (e.g. fig and ax are None).
center_plot – whether to center the figure on (0, 0), the currently fixed center that the axes are drawn around by default. Will only run if there is at least one axis in hive_plot.
buffer – fraction of the axes past which to buffer x and y dimensions (e.g. setting buffer to 0.1 will find the maximum radius spanned by any Axis instance and set the x and y bounds as (-max_radius - buffer * max_radius, max_radius + buffer * max_radius)).
show_axes_labels – whether to label the hive plot axes in the figure (uses Axis.long_name for each Axis.)
axes_labels_buffer – fraction which to radially buffer axes labels (e.g. setting axes_label_buffer to 1.1 will be 10% further past the end of the axis moving from the origin of the plot).
axes_labels_fontsize – font size for hive plot axes labels.
axes_off – whether to turn off Cartesian x, y axes in resulting matplotlib figure (default True hides the x and y axes).
node_kwargs – additional params that will be applied to all hive plot nodes. Note, these are kwargs that affect a plt.scatter() call. Node data values can also be used, see note above for more details.
axes_kwargs – additional params that will be applied to all axes. Note, these are kwargs that affect a plt.plot() call.
text_kwargs – additional kwargs passed to plt.text() call.
fig_kwargs – additional values to be called in plt.subplots() call. Note if figsize is added here, then it will be prioritized over the figsize parameter.
prioritize_array_over_color – if both array and color are provided by the user as edge kwargs for any subset of edges, then setting this to True will drop color and use array to color edges. If False, will instead use color. Default True.
edge_kwargs – additional params that will be applied to all edges on all axes (but kwargs specified beforehand in hiveplotlib.BaseHivePlot.connect_axes() or hiveplotlib.BaseHivePlot.add_edge_kwargs() will take priority). To overwrite previously set kwargs, see hiveplotlib.BaseHivePlot.add_edge_kwargs() for more. Note, these are kwargs that affect a matplotlib.collections.LineCollection() call. Edge data values can also be used, see note above for more details.

Returns:

matplotlib figure, axis.

hiveplotlib.viz.matplotlib.label_axes(instance: BaseHivePlot | HivePlot | P2CP, fig: Figure | None = None, ax: Axes | None = None, axes_labels_buffer: float = 1.1, axes_labels_fontsize: int = 16, buffer: float = 0.1, figsize: Tuple[float, float] = (10, 10), center_plot: bool = True, axes_off: bool = True, fig_kwargs: dict | None = None, **text_kwargs) → Tuple[Figure, Axes] | None#

matplotlib visualization of axis labels in a HivePlot or P2CP instance.

For HivePlot instances, each axis’ long_name attribute will be used. For P2CP instances, column names in the data attribute will be used.

Parameters:

instance – HivePlot or P2CP instance for which we want to draw nodes.
fig – default None builds new figure. If a figure is specified, axis labels will be drawn on that figure. Note: fig and ax must BOTH be None to instantiate new figure and axes.
ax – default None builds new axis. If an axis is specified, axis labels will be drawn on that axis. Note: fig and ax must BOTH be None to instantiate new figure and axes.
axes_labels_buffer – fraction which to radially buffer axes labels (e.g. setting axes_label_buffer to 1.1 will be 10% further past the end of the axis moving from the origin of the plot).
axes_labels_fontsize – font size for axes labels.
buffer – fraction of the axes past which to buffer x and y dimensions (e.g. setting buffer to 0.1 will find the maximum radius spanned by any Axis instance and set the x and y bounds as (-max_radius - buffer * max_radius, max_radius + buffer * max_radius)).
figsize – size of figure. Note: only works if instantiating new figure and axes (e.g. fig and ax are None).
center_plot – whether to center the figure on (0, 0), the currently fixed center that the axes are drawn around by default. Will only run if there is at least one axis in instance.
axes_off – whether to turn off Cartesian x, y axes in resulting matplotlib figure (default True hides the x and y axes).
fig_kwargs – additional values to be called in plt.subplots() call. Note if figsize is added here, then it will be prioritized over the figsize parameter.
text_kwargs – additional kwargs passed to plt.text() call.

Returns:

matplotlib figure, axis. If instance cannot be plotted with this function, returns None.

hiveplotlib.viz.matplotlib.node_viz(instance: BaseHivePlot | HivePlot | P2CP, fig: Figure | None = None, ax: Axes | None = None, figsize: Tuple[float, float] = (10, 10), center_plot: bool = True, buffer: float = 0.1, axes_off: bool = True, fig_kwargs: dict | None = None, **scatter_kwargs) → Tuple[Figure, Axes]#

matplotlib visualization of nodes in a HivePlot or P2CP instance that have been placed on its axes.

Note

If instance is a HivePlot, then users can provide node-specific data to plotting keyword arguments by providing column names from the HivePlot.nodes.data DataFrame as values in either the HivePlot.nodes.node_viz_kwargs dictionary via HivePlot.update_node_viz_kwargs() or in this call in the provided scatter_kwargs.

If instance is a HivePlot, then any provided node plotting keyword arguments in HivePlot.nodes.node_viz_kwargs will be prioritized over any provided scatter_kwargs.

Parameters:

instance – HivePlot or P2CP instance for which we want to draw nodes.
fig – default None builds new figure. If a figure is specified, nodes will be drawn on that figure. Note: fig and ax must BOTH be None to instantiate new figure and axes.
ax – default None builds new axis. If an axis is specified, nodes will be drawn on that axis. Note: ``fig` and ax must BOTH be None to instantiate new figure and axes.
figsize – size of figure. Note: only works if instantiating new figure and axes (e.g. fig and ax are None).
center_plot – whether to center the figure on (0, 0), the currently fixed center that the axes are drawn around by default. Will only run if there is at least one axis in instance.
buffer – fraction of the axes past which to buffer x and y dimensions (e.g. setting buffer to 0.1 will find the maximum radius spanned by any Axis instance and set the x and y bounds as (-max_radius - buffer * max_radius, max_radius + buffer * max_radius)).
axes_off – whether to turn off Cartesian x, y axes in resulting matplotlib figure (default True hides the x and y axes).
fig_kwargs – additional values to be called in plt.subplots() call. Note if figsize is added here, then it will be prioritized over the figsize parameter.
scatter_kwargs – additional params that will be applied to all hive plot nodes. Note, these are kwargs that affect a plt.scatter() call. Node data values can also be used, see note above for more details.

Returns:

matplotlib figure, axis.

hiveplotlib.viz.matplotlib.p2cp_legend(p2cp: P2CP, fig: Figure, ax: Axes, tags: Hashable | List[Hashable] | None = None, title: str = 'Tags', line_kwargs: dict | None = None, **legend_kwargs) → Tuple[Figure, Axes]#

Generate a legend for a P2CP instance, where entries in the legend will be tags of data added to the instance.

Parameters:

p2cp – P2CP instance we want to visualize.
fig – matplotlib figure on which we will draw the legend.
ax – matplotlib axis on which we will draw the legend.
tags – which tags of data to include in the legend. Default None uses all tags under p2cp.tags. This can be ignored unless explicitly wanting to exclude certain tags from the legend.
title – title of the legend. Default “Tags”.
line_kwargs – keyword arguments that will add to / overwrite _all_ of the legend line markers from the defaults used in the original P2CP instance plot. For example, if one plots a large number of lines with low alpha and / or a small lw, one will likely want to include line_kwargs=dict(alpha=1, lw=2) so the representative lines in the legend are legible.
legend_kwargs – additional params that will be applied to the legend. Note, these are kwargs that affect a plt.legend() call. Default is to plot the legend in the upper right, outside of the bounding box (e.g. loc="upper left", bbox_to_anchor=(1, 1)).

Returns:

matplotlib figure, axis.

hiveplotlib.viz.matplotlib.p2cp_viz(p2cp: P2CP, fig: Figure | None = None, ax: Axes | None = None, tags: Hashable | List[Hashable] | None = None, figsize: Tuple[float, float] = (10, 10), center_plot: bool = True, buffer: float = 0.1, show_axes_labels: bool = True, axes_labels_buffer: float = 1.1, axes_labels_fontsize: int = 16, axes_off: bool = True, node_kwargs: dict | None = None, axes_kwargs: dict | None = None, fig_kwargs: dict | None = None, **edge_kwargs) → Tuple[Figure, Axes]#

matplotlib visualization of a P2CP instance.

Parameters:

p2cp – P2CP instance we want to visualize.
fig – default None builds new figure. If a figure is specified, P2CP will be drawn on that figure. Note: fig and ax must BOTH be None to instantiate new figure and axes.
ax – default None builds new axis. If an axis is specified, P2CP will be drawn on that axis. Note: fig and ax must BOTH be None to instantiate new figure and axes.
tags – which tag(s) of data to plot. Default None plots all tags of data. Can supply either a single tag or list of tags.
figsize – size of figure. Note: only works if instantiating new figure and axes (e.g. fig and ax are None).
center_plot – whether to center the figure on (0, 0), the currently fixed center that the axes are drawn around by default. Will only run if there is at least one axis in p2cp.
buffer – fraction of the axes past which to buffer x and y dimensions (e.g. setting buffer to 0.1 will find the maximum radius spanned by any Axis instance and set the x and y bounds as (-max_radius - buffer * max_radius, max_radius + buffer * max_radius)).
show_axes_labels – whether to label the P2CP axes in the figure (uses Axis.long_name for each Axis.)
axes_labels_buffer – fraction which to radially buffer axes labels (e.g. setting axes_label_buffer to 1.1 will be 10% further past the end of the axis moving from the origin of the plot).
axes_labels_fontsize – font size for P2CP axes labels.
axes_off – whether to turn off Cartesian x, y axes in resulting matplotlib figure (default True hides the x and y axes).
node_kwargs – additional params that will be applied to all points on axes. Note, these are kwargs that affect a plt.scatter() call.
axes_kwargs – additional params that will be applied to all axes. Note, these are kwargs that affect a plt.plot() call.
fig_kwargs – additional values to be called in plt.subplots() call. Note if figsize is added here, then it will be prioritized over the figsize parameter.
edge_kwargs – additional params that will be applied to all edges on all axes (but kwargs specified beforehand in hiveplotlib.P2CP.build_edges() or hiveplotlib.P2CP.add_edge_kwargs() will take priority). To overwrite previously set kwargs, see hiveplotlib.P2CP.add_edge_kwargs() for more. Note, these are kwargs that affect a matplotlib.collections.LineCollection() call.

Returns:

matplotlib figure, axis.