Drawing

Clusters

Useful functions to draw clusters

plot_average_silhouettes(cluster_sets, ax=None)

Plot the average silhouettes across this range of cluster sets

Parameters

• cluster_sets (ClusterSets)

• ax (matplotlib.Axes, optional) – Axes on which to plot

Return type

None

plot_cluster_set(cluster_set, ax=None, y_height=0, cmap=<matplotlib.colors.ListedColormap object>, number_of_colors=10, colors=None)

Plots this cluster set as a scatter graph

Parameters

• cluster_set (pk.ClusterSet) – ClusterSet object containing partitions to plot

• ax (matplotlib.Axes, optional) – Axes on which to plot

• y_height (int or float, optional) – Height at which to plot (default 0)

• cmap (matplotlib.cm, optional) – Desired colour map (default ‘tab10’)

• number_of_colors (int, optional) – Desired number of colours to use for the colormap (default 10)

• colors (list of int, optional) – If None (default), cluster label 0 is assigned its automatic color “C0” and so on. If colors is a list (e.g. [3,1,2]), it relabels the clusters in that order and assigns them the new corresponding colors.

Return type

None

plot_cluster_sets(cluster_sets, axs=None, coloring='consistent', translation=None, with_silhouettes=False, with_n_clusters=False)

Plot these cluster sets as a scatter graph

Parameters

• cluster_sets (phasik ClusterSets) – ClusterSets object containing partitions to plot

• axs (matplotlib.Axes, optional) – Matplotlib axes on which to plot

• coloring ({‘ascending’, ‘consistent’, None}, optional)

• translation (dict, optional) – If None (default), has no effect. Elsee, dictionary that determines which label should be replaced by which other label For example {1: 2, 2: 3, 3: 1} It is applied after the order relabling from method.

• with_silhouettes (bool, optional)

• with_n_clusters (bool, optional)

Return type

None

plot_dendrogram(cluster_set, ax=None, distance_threshold=None, leaf_rotation=90, leaf_font_size=6)

Plot this cluster set as a dendrogram

Parameters

• ax (matplotlib.Axes, optional) – Axes on which to plot

• leaf_rotation (int or float, optional) – Rotation to apply to the x-axis (leaf) labels (default 90)

• leaf_font_size (int or str, optional) – Desired size of the x-axis (leaf) labels (default 6)

Return type

None

plot_ns_clusters(cluster_sets, ax=None)

Plot the average cluster set sizes across this range of cluster sets

Parameters

• cluster_sets (ClusterSets) – Cluster sets information to plot

• ax (matplotlib.Axes, optional) – Axes on which to plot

Return type

None

plot_randindex_bars_over_methods_and_sizes(valid_cluster_sets, reference_method='ward', ax=None, plot_ref=False)

Plot Rand Index as bars, to compare any method to a reference method.

This compares all combinations of methods and number of clusters.

Parameters

• valid_cluster_sets (list) – A list of tuples representing valid cluster sets. Each tuple contains the ClusterSet and the clustering method name.

• reference_method (str, optional) – The reference method to compare other methods to. Defaults to “ward”.

• ax (matplotlib.axes.Axes, optional) – The axes to plot the bars on. If not provided, the current axes will be used.

• plot_ref (bool, optional) – Determines whether to plot the reference method bars (will be one). Defaults to False.

Returns

The axes object containing the plotted bars.

Return type

matplotlib.axes.Axes

relabel_clusters_sorted(clusters, final_labels=None)

Returns array of cluster labels sorted in order of appearance, with clusters unchanged

Parameters

• clusters (array of int) – Cluster labels

• final_labels (array of int) – Cluster labels in expected order (has size of the number of clusters)

Example

>>> clusters = np.array([2, 2, 2, 3, 3, 1, 1, 1])
>>> relabel_clusters_sorted(clusters)
[ 1 1 1 2 2 3 3 3 ]

relabel_clustersets(cluster_sets, method='consistent', translation=None)

Relabels clusters in each cluster set, so that clusters are labeled consistently at different numbers of clusters.

This is especially useful when plotting cluster sets, to have consistent colouring.

Parameters

• cluster_sets (ClusterSets)

• method ({‘consistent’, ‘ascending’}, optional)

• translation (dict, optional) – If None (default), has no effect. Elsee, dictionary that determines which label should be replaced by which other label For example {1: 2, 2: 3, 3: 1} It is applied after the order relabling from method.

Returns

cluster_sets_sorted

Return type

ClusterSets

relabel_clustersets_from_dict(cluster_sets, translation)

Relabels clusters in each cluster set, so that clusters are labeled according to the translation dictionary

This is especially useful when plotting cluster sets, to have consistent colouring. between different figures with cluster sets.

Parameters

• cluster_sets (ClusterSets)

• translation (dict) – Dictionary that determines which label should be replaced by which other label For example {1: 2, 2: 3, 3: 1}

Returns

cluster_sets_sorted

Return type

ClusterSets

relabel_next_clusterset_sorted(cluster_sets, cluster_sets_sorted, i)

Relabels the clusters in i+1th cluster set so that it is consistent with ith cluster set

This is especially useful when plotting cluster sets, to have consistent colouring.

Parameters

• cluster_sets (ClusterSets) – Original cluster sets

• cluster_sets_sorted (ClusterSets) – Cluster sets being sorted, already sorted up to i-1

• i (int)

Returns

cluster_sets_sorted

Return type

ClusterSets

Networks

Functions to visualise networks and temporal networks

animate_temporal_network(temporal_network, color_temporal='red', color_constant='silver', width_scale=1.5, with_labels=True, pos=None, ax=None, interval=20, frames=None)

Return animation of the temporal network evolving over time

Parameters

• temporal_network (phasik.TemporalNetwork) – Temporal network to visualise

• color_temporal (str) – Color of the time-varying edges, defaults to ‘red’

• color_constant (str) – Color of the constant edges (defaults to ‘silver’), i.e. for which we have no temporal information

• width_scale (float) – Scale factor for width of the temporal edges compared to the constant ones

• pos (dict) – Dictionary of node positions

• ax (matplotlib.axis) – Axes to plot the animation on

• interval (int) – Interval of time between frames, in ms.

• frames (int) – Number of frames of the animation (should be at most the number of timepoints (default))

Return type

matplotlib.animation

draw_graph(graph, ax=None, label_nodes=True, color='mediumseagreen', pos=None, edge_widths=None, edge_colors=None, edge_cmap=None, edge_vmin=None, edge_vmax=None)

Basic graph drawing function

Parameters

• graph (networkx.Graph) – Graph to visualise

• ax (matplotlib.Axes, optional) – Axes on which to draw the graph

• label_nodes (bool, optional) – Whether to label the nodes or just leave them as small circles (default True)

• color (str, optional) – Color to use for the graph nodes and edges (default ‘mediumseagreen’)

• pos (dict) – Dictionary of node positions

• edge_widths (float or array of floats) – Line width of edges

• edge_colors (color or array of colors) – Edge color. Can be a single color or a sequence of colors with the same length as edgelist. Color can be string or rgb (or rgba) tuple of floats from 0-1. If numeric values are specified they will be mapped to colors using the edge_cmap and edge_vmin,edge_vmax parameters.

• edge_cmap (Matplotlib colormap, optional) – Colormap for mapping intensities of edges

• edge_vmin,edge_vmax (floats, optional) – Minimum and maximum for edge colormap scaling

Return type

None

highlight_subgraphs(graphs, colors, ax=None, pos=None, label_nodes=True)

Draw multiple nested subgraphs on the same axes

Parameters

• graphs (list of networkx.Graph)

• colors (list of str) – List of colors, one for each of the graphs in ‘graphs’

• ax (matplotlib.Axes, optional) – Axes to plot on

• label_nodes (bool, optional) – Whether or not to label the graph nodes or leave them as circles

• pos (dict) – Dictionary of node positions

Return type

None

standard_edge_params(color)

Returns a dictionary containing standard values of edge plotting parameters

standard_label_params(color)

Returns a dictionary containing standard values of label plotting parameters

standard_node_params(color)

Returns a dictionary containing standard values of node plotting parameters

standard_params(color)

Returns a dictionary containing standard values of plotting parameters

Drawing

Useful drawing functions

plot_edge_series(temporal_network, edges, ax=None)

Plot timeseries of edge weights, for the specified edges

Parameters

• temporal_network (pk.TempNet) – Temporal network

• edge (list of str) – List of edges to plot

• ax (matplotlib.Axes, optional) – Axes to use

Return type

ax

plot_events(events, ax=None, text_y_pos=None, text_x_offset=0, period=None, n_periods=1, add_labels=True, orientation='vertical', zorder=- 1, alpha=1, va='bottom')

Plot events as vertical lines on axes

Parameters

• events (list of tuples (time, name, line_style)) – time - time at which the event occurred name - the name of the event line_style - any string accepted by matplotlib.lines.Line2D.set_linestyle

• ax (matplotlib.Axes, optional) – Axes on which to plot the events

• text_y_pos (float, optional) – Height at which to place the name of the event (default None)

• text_x_offset (float, optional) – Distance along x-axis by which to offset the placement of the event name (default 0)

• period (float or None, optional) – Length of time of one period, if events repeat periodically.

• n_periods (int, optional) – Number of periods to draw, if events repeat periodically.

• add_labels (bool, optional) – Wether to display the label of each vertical line, True by default.

Return type

None

plot_interval(binary_series, times, y=0, peak=None, color='k', ax=None, zorder=0)

Plot a binary series as a sequence of coloured intervals

Specifically, when a binary series has value 1, plot it as a continuous rectangular interval. When it has value 0 do nothing.

Parameters

• binary_series (ndarray) – 2D array of binary data to plot

• times (ndarray) – 1D array consisting of the corresponding time points

• y (float, optional) – Height (y-axis value) at which to plot the interval (default 0)

• color (str, optional) – Color to use for the intervals (default ‘k’)

• ax (matplotlib.Axes, optional) – Axes to plot on

• zorder (int, optional) – Height on the z-axis which to plot the interval (default 0)

Return type

None

plot_phases(phases, ax=None, y_pos=None, ymin=0, ymax=1, t_offset=0)

Plot phases as shaded regions on axes

Parameters

• phases (list of tuples (start_time, end_time, name))

• ax (matplotlib.Axes) – Axes on which to plot the phases

• y_pos (float or None, optional) – Height at which to place the name of the phase

• ymin (float, optional) – Height at which to start shaded region (default 0)

• ymax (float, optional) – Height at which to stop shaded region (default 1)

• t_offset (float, optional) – Offset of phase on the time axis

Return type

None

threshold_plot(x, y, threshold, color_below_threshold, color_above_threshold, ax=None)

Plot values above a certain threshold in a particular colour

Parameters

• x (array) – 1D array of alues to plot along x-axis

• y (array) – 1D array of values to plot along y-axis

• threshold (float) – Only plot in colour the points (x,y) with y >= threshold

• colour_below_threshold (str) – Colour to use for points below threshold

• colour_above_threshold (list of str) – Colour to use for points above threshold

• ax (matplotlib.Axes, optional) – Axes to use

Return type

None

Utils

General utility functions for plots

adjust_margin(ax=None, top=0, bottom=0, left=0, right=0)

Extend the margin of a plot by a percentage of its original width/height

Parameters

• ax (matplotlib.Axes, optional) – Axes whose margins to adjust

• top (float, optional) – Percentage (as decimal) by which to increase top margin

• bottom (float, optional) – Percentage (as decimal) by which to increase bottom margin

• left (float, optional) – Percentage (as decimal) by which to increase left margin

• right (float, optional) – Percentage (as decimal) by which to increase right margin

Return type

None

configure_sch_color_map(cmap)

Set SciPy’s colour palette to use a particular colour map

display_name(key)

Get a more user-friendly name for certain keywords.

This function takes a keyword key and returns a more user-friendly name for that keyword if it exists in the predefined names dictionary. If the keyword is not found in the dictionary, it is returned as is.

Parameters

key (str) – The keyword for which a display name is needed.

Returns

The display name for the given keyword, or the original keyword if not found.

Return type

str

Examples

>>> display_name('maxclust')
'Max # clusters'
>>> display_name('distance')
'Distance threshold'
>>> display_name('unknown')
'unknown'

label_subplot_grid_with_shared_axes(rows, columns, total_subplots, xlabel, ylabel, fig, axes)

Method to tidy up cases where we have a grid of plots with shared axes, by deleting unused subplots (if number of of subplots is not rectangular) and adding axes ticks

Parameters

• rows (int) – Number of rows in the grid of subplots

• columns (int) – Number of columns in the grid of subplots

• total_subplots (int) – Number of subplots in the grid; need not be a ‘rectangular’ number

• xlabel (str) – Label of the x-axis

• ylabel (str) – Label of the y-axis

• fig (matplotlib.Figure) – Figure that the subplots are a part of

• axes (list of matplotlib.Axes) – Axes containing the subplots

Return type

None

palette_20_ordered(as_map=False)

Create an ordered color palette of 20 colors.

The function uses the ‘tab20’ color palette from seaborn and rearranges the colors in an ordered pattern. By default, the colors are returned as a list, but if as_map is set to True, a ListedColormap object is returned.

Parameters

as_map (bool, optional) – Whether to return the colors as a ListedColormap object (default is False).

Returns

The ordered color palette. If as_map is True, a ListedColormap object is returned.

Return type

list or ListedColormap