Plotly#

plotly-backend visualizations in hiveplotlib.

hiveplotlib.viz.plotly.axes_viz(instance: BaseHivePlot | HivePlot | P2CP, fig: Figure | None = None, line_width: float = 1.5, opacity: float = 1.0, buffer: float = 0.3, show_axes_labels: bool = True, axes_labels_buffer: float = 1.25, axes_labels_fontsize: float = 16, width: int = 600, height: int = 600, center_plot: bool = True, axes_off: bool = True, layout_kwargs: dict | None = None, hover: bool = True, label_kwargs: dict | None = None, **line_kwargs) → Figure | None#

Visualize axes in a HivePlot or P2CP instance with plotly.

Note

The line_width parameter corresponds to the standard width parameter for plotly lines. We are exposing this parameter with a different name because width is already the standard name for figure width throughout hiveplotlib.viz.

plotly out of the box does not support standard opacity for its line plots like it does for scatter plots, but it does support providing an alpha channel in RGBA / HSVA / HSLA strings. The opacity parameter in this function call will behave as opacity behaves for plotly scatter plots, as long as the user-provided colors are either standard named CSS colors (e.g. “blue”, “navy”, “green”) or hex colors.

Users who prefer to provide colors as multi-channel RGBA / HSVA / HSLA strings will override the opacity parameter. For more on how to provide multi-channel color strings, see the plotly docs for the color parameter for lines.

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.

  • line_width – width of axes.

  • opacity – opacity of edges. Must be in [0, 1].

  • buffer – fraction of the axes past which to buffer x and y dimensions (e.g. setting buffer 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.

  • width – width of figure in pixels. Note: only works if instantiating new figure (e.g. fig is None).

  • height – height of figure in pixels. Note: only works if instantiating new figure (e.g. fig is 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 plotly figure (default True hides the x and y axes).

  • layout_kwargs – additional values for the layout parameter to be called in plotly.graph_objects.Figure() call. Note, if width and height are added here, then they will be prioritized over the width and height parameters.

  • hover – whether to add hover information or not for axes. False excludes hover information. Default True. Hover info will appear over axes labels. Only works currently for Hive Plots, not P2CPs.

  • label_kwargs – additional kwargs passed to the textfont parameter of plotly.graph_objects.Scatter(). For examples of parameter options, see the plotly docs.

  • line_kwargs – additional params that will be applied to all hive plot axes. Note, these are kwargs that affect a plotly.graph_objects.scatter.Line() call.

Raises:

ValueError – if opacity is not in [0, 1].

Returns:

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

hiveplotlib.viz.plotly.edge_viz(instance: BaseHivePlot | HivePlot | P2CP, fig: Figure | None = None, tags: Hashable | List[Hashable] | None = None, line_width: float | None = None, opacity: float | None = None, width: int = 600, height: int = 600, center_plot: bool = True, buffer: float = 0.3, axes_off: bool = True, layout_kwargs: dict | None = None, hover: bool = True, **edge_kwargs) → Figure#

Visualize constructed edges in a HivePlot or P2CP instance with plotly.

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:

  1. HivePlot.edge_plotting_keyword_arguments attribute via HivePlot.update_edge_plotting_keyword_arguments().

  2. HivePlot.edges.edge_viz_kwargs attribute via HivePlot.edges.update_edge_viz_kwargs().

  3. 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.

The line_width parameter corresponds to the standard width parameter for plotly lines. We are exposing this parameter with a different name because width is already the standard name for figure width throughout hiveplotlib.viz.

plotly out of the box does not support standard opacity for its line plots like it does for scatter plots, but it does support providing an alpha channel in RGBA / HSVA / HSLA strings. The opacity parameter in this function call will behave as opacity behaves for plotly scatter plots, as long as the user-provided colors are either standard named CSS colors (e.g. “blue”, “navy”, “green”) or hex colors.

Users who prefer to provide colors as multi-channel RGBA / HSVA / HSLA strings will override the opacity parameter. For more on how to provide multi-channel color strings, see the plotly docs for the color parameter for lines.

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.

  • 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.

  • line_width – width of edges. Default None sets line width to 1.5 if not provided by any other keyword arguments.

  • opacity – opacity of edges. Must be in [0, 1]. Default None sets opacity to 0.5 if not provided by any other keyword arguments.

  • width – width of figure in pixels. Note: only works if instantiating new figure (e.g. fig is None).

  • height – height of figure in pixels. Note: only works if instantiating new figure (e.g. fig is 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 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 plotly figure (default True hides the x and y axes).

  • layout_kwargs – additional values for the layout parameter to be called in plotly.graph_objects.Figure() call. Note, if width and height are added here, then they will be prioritized over the width and height parameters.

  • hover – whether to add hover information or not for edges. False excludes hover information. Default True. Only works currently for Hive Plots, not P2CPs.

  • 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 plotly.graph_objects.scatter.Line() call. Edge data values can also be used, see note above for more details.

Raises:

ValueError – if opacity is not in [0, 1].

Returns:

plotly figure.

hiveplotlib.viz.plotly.hive_plot_viz(hive_plot: BaseHivePlot | HivePlot, fig: Figure | None = None, tags: Hashable | List[Hashable] | None = None, width: int = 600, height: int = 600, center_plot: bool = True, buffer: float = 0.3, show_axes_labels: bool = True, axes_labels_buffer: float = 1.25, axes_labels_fontsize: float = 16, axes_off: bool = True, node_kwargs: dict | None = None, axes_kwargs: dict | None = None, label_kwargs: dict | None = None, layout_kwargs: dict | None = None, hover: bool | Literal['nodes', 'edges', 'axes'] | list[Literal['nodes', 'edges', 'axes']] = True, **edge_kwargs) → Figure#

Create default plotly 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:

  1. HivePlot.edge_plotting_keyword_arguments attribute via HivePlot.update_edge_plotting_keyword_arguments().

  2. HivePlot.edges.edge_viz_kwargs attribute via HivePlot.edges.update_edge_viz_kwargs().

  3. In this call in the provided edge_kwargs.

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.

The line width and opacity of axes can be changed by including the line_width and opacity parameters, respectively, in axes_kwargs. See the documentation for hiveplotlib.viz.plotly.axes_viz() for more information.

If the line width and opacity of edges was not set in the original hive plot, then these parameters can be set by including the line_width and opacity parameters, respectively, as additional keyword arguments. See the documentation for hiveplotlib.viz.plotly.edge_viz() for more information.

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.

  • 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.

  • width – width of figure in pixels. Note: only works if instantiating new figure (e.g. fig is None).

  • height – height of figure in pixels. Note: only works if instantiating new figure (e.g. fig is 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 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 plotly 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 plotly.graph_objects.scatter.Marker() call. Node data values can also be used, see note above for more details.

  • axes_kwargs – additional params that will be applied to all hive plot axes. This includes the line_width and opacity parameters in hiveplotlib.viz.plotly.axes_viz(). Note, these are kwargs that affect a plotly.graph_objects.scatter.Line() call.

  • label_kwargs – additional kwargs passed to the textfont parameter of plotly.graph_objects.Scatter(). For examples of parameter options, see the plotly docs.

  • layout_kwargs – additional values for the layout parameter to be called in plotly.graph_objects.Figure() call. Note, if width and height are added here, then they will be prioritized over the width and height parameters.

  • hover – whether to add hover information or not for nodes, edges, and / or axes. False excludes all hover information, while default True includes node, edge, and axis hover information. Providing the value "nodes" / "edges" / "axes" adds hover information ONLY for nodes / edges / axes. Users can also provide a list of a subset of these values (e.g. providing ["nodes", "edges"] would show all hover info except for axes).

  • 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). This includes the line_width and opacity parameters in hiveplotlib.viz.plotly.edge_viz(). To overwrite previously set kwargs, see hiveplotlib.BaseHivePlot.add_edge_kwargs() for more. Note, these are kwargs that affect a plotly.graph_objects.scatter.Line() call. Edge data values can also be used, see note above for more details.

Raises:
Returns:

plotly figure.

hiveplotlib.viz.plotly.label_axes(instance: BaseHivePlot | HivePlot | P2CP, fig: Figure | None = None, axes_labels_buffer: float = 1.25, axes_labels_fontsize: float = 16, buffer: float = 0.3, width: int = 600, height: int = 600, center_plot: bool = True, axes_off: bool = True, layout_kwargs: dict | None = None, hover: bool = True, **label_kwargs) → Figure | None#

Visualize axis labels in a HivePlot or P2CP instance with plotly.

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.

  • 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 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)).

  • width – width of figure in pixels. Note: only works if instantiating new figure (e.g. fig is None).

  • height – height of figure in pixels. Note: only works if instantiating new figure (e.g. fig is 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 plotly figure (default True hides the x and y axes).

  • layout_kwargs – additional values for the layout parameter to be called in plotly.graph_objects.Figure() call. Note, if width and height are added here, then they will be prioritized over the width and height parameters.

  • hover – whether to add hover information or not over axes labels. False excludes hover information. Default True. Only works currently for Hive Plots, not P2CPs.

  • label_kwargs – additional kwargs passed to the textfont parameter of plotly.graph_objects.Scatter(). For examples of parameter options, see the plotly docs.

Returns:

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

hiveplotlib.viz.plotly.node_viz(instance: BaseHivePlot | HivePlot | P2CP, fig: Figure | None = None, width: int = 600, height: int = 600, center_plot: bool = True, buffer: float = 0.3, axes_off: bool = True, layout_kwargs: dict | None = None, hover: bool = True, **scatter_kwargs) → Figure#

Visualize of nodes in a HivePlot or P2CP instance that have been placed on their axes in plotly.

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.

  • width – width of figure in pixels. Note: only works if instantiating new figure (e.g. fig is None).

  • height – height of figure in pixels. Note: only works if instantiating new figure (e.g. fig is 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 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 plotly figure (default True hides the x and y axes).

  • layout_kwargs – additional values for the layout parameter to be called in plotly.graph_objects.Figure() call. Note, if width and height are added here, then they will be prioritized over the width and height parameters.

  • hover – whether to add hover information or not for nodes. False excludes hover information. Default True. Only works currently for Hive Plots, not P2CPs.

  • scatter_kwargs – additional params that will be applied to all hive plot nodes. Note, these are kwargs that affect a plotly.graph_objects.scatter.Marker() call. Node data values can also be used, see note above for more details.

Raises:

ValueError – if any provided opacity value is not in [0, 1].

Returns:

plotly figure.

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

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 – plotly figure 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”.

  • legend_kwargs – additional values for the legend parameter in the plotly.graph_objects.update_layout() call.

Returns:

plotly figure.

hiveplotlib.viz.plotly.p2cp_viz(p2cp: P2CP, fig: Figure | None = None, tags: Hashable | List[Hashable] | None = None, width: int = 600, height: int = 600, center_plot: bool = True, buffer: float = 0.3, show_axes_labels: bool = True, axes_labels_buffer: float = 1.25, axes_labels_fontsize: float = 16, axes_off: bool = True, node_kwargs: dict | None = None, axes_kwargs: dict | None = None, label_kwargs: dict | None = None, layout_kwargs: dict | None = None, **edge_kwargs) → Figure#

Create default plotly visualization of a P2CP instance.

Note

The line width and opacity of axes can be changed by including the line_width and opacity parameters, respectively, in axes_kwargs. See the documentation for hiveplotlib.viz.plotly.axes_viz() for more information.

If the line width and opacity of edges was not set in the original P2CP, then these parameters can be set by including the line_width and opacity parameters, respectively, as additional keyword arguments. See the documentation for hiveplotlib.viz.plotly.edge_viz() for more information.

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.

  • 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.

  • width – width of figure in pixels. Note: only works if instantiating new figure (e.g. fig is None).

  • height – height of figure in pixels. Note: only works if instantiating new figure (e.g. fig is 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 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 plotly figure (default True hides the x and y axes).

  • node_kwargs – additional params that will be applied to all P2CP nodes. Note, these are kwargs that affect a plotly.graph_objects.scatter.Marker() call.

  • axes_kwargs – additional params that will be applied to all P2CP axes. This includes the line_width and opacity parameters in hiveplotlib.viz.plotly.axes_viz(). Note, these are kwargs that affect a plotly.graph_objects.scatter.Line() call.

  • label_kwargs – additional kwargs passed to the textfont parameter of plotly.graph_objects.Scatter(). For examples of parameter options, see the plotly docs.

  • layout_kwargs – additional values for the layout parameter to be called in plotly.graph_objects.Figure() call. Note, if width and height are added here, then they will be prioritized over the width and height parameters.

  • 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). This includes the line_width and opacity parameters in hiveplotlib.viz.plotly.edge_viz(). To overwrite previously set kwargs, see hiveplotlib.P2CP.add_edge_kwargs() for more. Note, these are kwargs that affect a plotly.graph_objects.scatter.Line() call.

Raises:

ValueError – if any provided opacity value is not in [0, 1].

Returns:

plotly figure.