P2CP Class#

class hiveplotlib.P2CP(data: DataFrame | None = None)#

Polar Parallel Coordinates Plots (P2CPs).

Conceptually similar to Hive Plots, P2CPs can be used for any multivariate data as opposed to solely for network visualizations. Features of the data are placed on their own axes in the same polar setup as Hive Plots, resulting in each representation of a complete data point being a loop in the resulting figure. For more on the nuances of P2CPs, see Koplik and Valente, 2021.

add_edge_kwargs(tag: Hashable | None = None, **edge_kwargs) → None#

Add edge kwargs to a tag of Bézier curves previously constructed with P2CP.build_edges().

For a given tag of curves for which edge kwargs were already set, any redundant edge kwargs specified by this method call will overwrite the previously set kwargs.

Note

Expected to have previously called P2CP.build_edges() before calling this method, for the tag of interest. However, if no tags were ever set (e.g. there’s only 1 tag of curves), then no tag is necessary here.

Parameters:

  • tag – which subset of curves to modify kwargs for. Note, if no tag is specified (e.g. tag=None), it is presumed there is only one tag to look over and that will be inferred. If no tag is specified and there are multiple tags to choose from, a ValueError will be raised.

  • edge_kwargs – additional matplotlib keyword arguments that will be applied to edges constructed for the referenced indices.

Returns:

None.

build_edges(indices: List[int] | ndarray | Literal['all'] = 'all', tag: Hashable | None = None, num_steps: int = 100, **edge_kwargs) → Hashable#

Construct the loops of the P2CP for the specified subset of indices.

These index values correspond to the indices of the pandas dataframe P2CP.data.

Note

Specifying indices="all" draws the curves for the entire dataframe.

Parameters:

  • indices – which indices of the underlying dataframe to draw on the P2CP. Note, “all” draws the entire dataframe.

  • tag – tag corresponding to specified indices. If None is provided, the tag will be set as the lowest unused integer starting at 0 amongst the tags.

  • num_steps – number of points sampled along a given Bézier curve. Larger numbers will result in smoother curves when plotting later, but slower rendering.

  • edge_kwargs – additional matplotlib keyword arguments that will be applied to edges constructed for the referenced indices.

Returns:

the unique, Hashable tag used for the constructed edges.

copy() → P2CP#

Return a copy of the P2CP instance.

Returns:

P2CP instance.

reset_edges(tag: Hashable | None = None) → None#

Drop the constructed edges with the specified tag.

Note

If no tags were ever set (e.g. there’s only 1 tag of curves), then no tag is necessary here.

Parameters:

tag – which subset of curves to delete. Note, if no tag is specified (e.g. tag=None), then all curves will be deleted.

Returns:

None.

set_axes(columns: List[Hashable] | ndarray, angles: List[float] | ndarray | None = None, vmins: List[float | None] | None = None, vmaxes: List[float | None] | None = None, axis_kwargs: List[Dict | None] | None = None, overwrite_previously_set_axes: bool = True, start_angle: float = 0) → None#

Set the axes that will be used in the eventual P2CP visualization.

Parameters:

  • columns – column names from P2CP.data to use. Note, these need not be unique, as repeat axes may be desired. By default, repeat column names will be internally renamed to name + "\nRepeat".

  • angles – corresponding angles (in degrees) to set for each desired axis. Default None sets the angles evenly spaced over 360 degrees, starting at start_angle degrees for the first axis and moving counterclockwise.

  • vmins – list of float values (or None values) specifying the vmin for each axis, where the ith index value corresponds to the ith axis set by columns. A None value infers the global min for that axis. Default None uses the global min for all axes.

  • vmaxes – list of float values (or None values) specifying the vmax for each axis, where the ith index value corresponds to the ith axis set by columns. A None value infers the global max for that axis. Default None uses the global max for all axes.

  • axis_kwargs – list of dictionaries of additional kwargs that will be used for the underlying Axis instances that will be created for each column. Only relevant if you want to change the positioning / length of an axis with the start and end parameters. For more on these kwargs, see the documentation for hiveplotlib.Axis. Note, if you want to add these kwargs for only a subset of the desired axes, you can skip adding kwargs for specific columns by putting a None at those indices in your axis_kwargs input.

  • overwrite_previously_set_axes – Whether to overwrite any previously decided axes. Default True overwrites any existing axes.

  • start_angle – if angles is None, sets the starting angle from which we place the axes around the origin counterclockwise.

Returns:

None.

set_data(data: DataFrame) → None#

Add a dataset to the P2CP instance.

All P2CP construction will be based on this dataset, which will be stored as P2CP.data.

Parameters:

data – dataframe to add.

Returns:

None.

to_json() → str#

Return the information from the axes, point placement on each axis, and edges in Cartesian space as JSON.

This allows users to visualize P2CPs with arbitrary libraries, even outside of python.

The dictionary structure of the resulting JSON will consist of two top-level keys:

“axes” - contains the information for plotting each axis, plus the points on each axis in Cartesian space.

“edges” - contains the information for plotting the discretized edges in Cartesian space broken up by tag values, plus the corresponding unique IDs of points that go with each tag, as well as any kwargs that were set for plotting each set of points in a given tag.

Returns:

JSON output of axis, point, and edge information.