API reference#

vizent.add_glyphs(ax, x_values, y_values, color_values, shape_values, size_values, colormap='viridis', scale_diverges=None, shape='sine', shape_pos='sine', shape_neg='square', color_max=None, color_min=None, color_n=None, color_spread=None, shape_max=None, shape_min=None, shape_n=None, shape_spread=None, color_label='color', shape_label='shape', legend_title='glyphs', scale_dp=2, interval_type='closest', legend_marker_size='auto', label_fontsize=None)#

Add glyphs/nodes to the plot.

Parameters:

ax (tuple (matplotlib.figure, matplotlib.axes.Axes, matplotlib.axes.Axes, matplotlib.axes.Axes, Numerical)) – The tuple of matplotlib figure and axes objects returned by create_plot().
x_values (float or array-like, shape (n,)) – Positions of glyphs on the x-axis.
y_values (float or array-like, shape (n,)) – Positions of glyphs on the y-axis.
color_values (float or array-like, shape (n,)) – The values to be represented by the color of each glyph.
shape_values (float or array-like, shape (n,)) – the list of values to be represented by the outer shape of each glyph.
size_values (float or array-like, shape(n,)) – the list of values in points for the diameter of each glyph.
colormap (matplotlib.colors.Colormap or str, optional) – the matplotlib colormap to be used. The default is viridis.
scale_diverges (boolean, optional) – If True, diverging sets of glyphs are used for positive and negative values. If not specified, your scale will diverge if both positive and negative values are included for the shape variable.
shape ('sine', 'saw', 'reverse_saw', 'square', 'triangular', 'concave', 'star'.) – Glyph shape design to use for non-divergent scales. Default 'sine'.
shape_pos ('sine', 'saw', 'reverse_saw', 'square', 'triangular', 'concave', 'star') – When using divergent scale, glyph shape design to use for positive values. Options as for shape. Default 'sine'.
shape_neg ('sine', 'saw', 'reverse_saw', 'square', 'triangular', 'concave', 'star') – When using divergent scale, glyph shape design to use for negative values. Options as for shape. Default 'square'.
color_max (float, optional) – The maximum color value in the legend.
color_min (float, optional) – The minimum color value in the legend.
color_n (int, optional) – The number of color values to show in the legend. If not set, a colorbar will be used representing a continuous colour scale.
color_spread (float, optional) – Range of color values in key. Only used if not specifying both max and min.
shape_max (float, optional) – The maximum shape value in the legend.
shape_min (float, optional) – The minimum shape value in the legend.
shape_n (int, optional) – The number of shape values to show in the legend.
shape_spread (float, optional) – Range of shape values in key. Only used if not specifying both max and min.
color_label (str, optional) – The title for the color component of the legend. Defaults to 'color'.
shape_label (str, optional) – The title for the shape component of the legend. Defaults to 'shape'.
legend_title (str, optional) – The main title for the glyph legend. Defaults to 'glyphs'.
scale_dp (int, optional) – The number of decimal places to round to for legend values. Defaults to 2.
interval_type (('closest', 'limit')) – Defines how the shape of each glyph is determined from its value. 'closest' uses the closest scale value, limit uses the highest scale value that the glyph value is greater than or equal to (using absolute values for negative values). Defaults to 'closest'.
legend_marker_size (('auto', 'mean')) – This controls the diameter of the legend glyph markers. 'auto' means the diameter is calculated automatically to fit. 'mean' uses the mean diameter/size value of the plotted glyphs.
label_fontsize (int, optional) – Fontsize for legend labels. If not set, this will be estimated based on the lengths of the labels.

Returns:

List of length n, containing the artist objects that constitute the plotted glyphs.

Return type:

list of artists

vizent.add_lines(ax, x_starts, y_starts, x_ends, y_ends, color_values, freq_values, width_values, striped_length=1, length_type='units', colormap='viridis', style='middle', color_max=None, color_min=None, color_n=None, color_spread=None, freq_max=None, freq_min=None, freq_n=None, freq_spread=None, color_label='color', frequency_label='frequency', legend_title='lines', scale_dp=2, interval_type='closest', legend_marker_size='auto', zorder=0.5, label_fontsize=None)#

Add lines/edges to the plot.

Parameters:

ax (tuple (matplotlib.figure, matplotlib.axes.Axes, matplotlib.axes.Axes, matplotlib.axes.Axes, Numerical)) – The tuple of matplotlib figure and axes objects returned by create_plot().
x_starts (float or array-like, shape (n,)) – The x coordinates of the origin points of each line
y_starts (float or array-like, shape (n,)) – The y coordinates of the origin points of each line
x_ends (float or array-like, shape (n,)) – The x coordinates of the end points of each line
y_ends (float or array-like, shape (n,)) – The y coordinates of the end points of each line
color_values (float or array-like, shape (n,)) – The values to be represented by the color of each line.
freq_values (float or array-like, shape (n,)) – The list of values to be represented by the central stripe frequency.
width_values (float or array-like, shape(n,)) – The list of values in points for the width of each line.
striped_length (float, optional) – if using the style 'set_length', the length of the central stripe. Units determined by length_type. Defaults to 1.
length_type (('units', 'pixels', 'proportion'), optional) – The units to be used for stripe length. 'units' uses axes units, 'pixels' uses the number of pixels and 'proportion' uses the proportion of the line.
colormap (matplotlib.colors.Colormap or str, optional) – the matplotlib colormap to be used. Defaults to viridis.
style (('middle', 'ends', 'source', 'destination', 'set_length', 'frequency', 'off'), optional.) – The length and positioning style of the striped area. 'middle' generates a striped area centred on the line/edge where with length of striped area 1/3 of edge length. 'ends' generates a striped area at each end of the line/edge with length of striped area 1/4 of total edge length. 'source' generates a striped area at the source of the line, 1/2 of the total edge length. 'destination' generates a striped area at the line destination, where the striped area is 1/2 of the total edge length. 'set_length' generates a striped area at the centre of the line, with the length specified by user via the striped_length parameter, 'frequency' generates a striped area at the centre of the line, 1/3 edge length. Instead of a set number of stripes, this uses the number of stripes per unit length, matched to the legend. 'off' turns off the striped area. Defaults to 'middle'.
color_max (float, optional) – The maximum color value in the legend.
color_min (float, optional) – The minimum color value in the legend.
color_n (int, optional) – The number of color values to show in the legend.
color_spread (float, optional) – Range of color values in key. Only used if not specifying both max and min.
freq_max (float, optional) – The maximum frequency value in the legend.
freq_min (float, optional) – The minimum frequency value in the legend.
freq_n (int, optional) – The number of frequency values to show in the legend.
freq_spread (float, optional) – Range of frequency values in key. Only used if not specifying both max and min.
color_label (str, optional) – The title for the color component of the legend. Defaults to 'color'.
freq_label – The title for the frequency component of the legend. Defaults to 'frequency'.
legend_title (str, optional) – The main title for the glyph legend. Defaults to 'lines'.
scale_dp (int, optional) – The number of decimal places to round to for legend values. Defaults to 2.
interval_type (('closest', 'limit')) – Defines how the frequency of each line is determined from its value. 'closest' uses the closest scale value, limit uses the highest scale value that the frequency value is greater than or equal to (using absolute values for negative values). Defaults to 'closest'.
legend_marker_size (('auto', 'mean')) – This controls the width of the legend line markers. 'auto' means the width is calculated automatically to fit. 'mean' uses the mean width value of the plotted lines.

Returns:

List of length n, containing the artist objects that constitute the plotted lines.

Return type:

list of artists

vizent.create_plot(use_glyphs=True, use_lines=True, show_legend=True, show_axes=True, use_cartopy=False, cartopy_projection=None, use_image=False, image_type=None, image_file=None, extent=None, scale_x=None, scale_y=None)#

Create the figure used to plot glyphs and/or lines. This function must be executed first, and the output is used as an input to all other functions.

Parameters:

use_glyphs (boolean, optional) – Set True if glyphs are to be plotted, defaults to True.
use_lines (boolean, optional) – Set True if lines are to be plotted, defaults to True.
show_legend (boolean, optional) – If True, show legends for glyphs/lines as included, defaults to True.
show_axes (boolean, optional) – If True, show axis labels, defaults to True
use_cartopy (boolean, optional) – If True, use Cartopy to generate a map background. Must specify extent if used. Defaults to False.
use_image (boolean, optional) – If True, use an image as a background. Must specify extent if used. Defaults to False.
image_type (str, optional) – Use either pre-packaged images or a user supplied image as a background, defaults to None. newcastle provides a detailed 3D rendered image of Newcastle Upon Tyne (available for limited coordinates). england provides a map of England from OpenStreetMap. filepath can also be provided for any user supplied image.
extent (list, optional) – Axis limits or extent of coordinates for Cartopy. A list of four values in the form: [xmin, xmax, ymin, ymax].
scale_x (int, optional) – Width of plot window in inches
scale_y (int, optional) – Height of plot window in inches

Returns:

tuple containing: fig Matplotlib figure object which will contain the axes. ax1 The matplotlib axes object for the main plot. ax2 The matplotlib axes object used for the glyph legend. ax3 The matplotlib axes object used for the line legend. asp The aspect ratio of the main plot area (necessary to ensure the legends display correctly when using image or map backgrounds).

Return type:

(matplotlib.figure, matplotlib.axes.Axes, matplotlib.axes.Axes, matplotlib.axes.Axes, float)

vizent.return_figure(fig, return_type, file_name='vizent_plot_save')#

Return the created figure by your chosen method

Parameters:

fig – The tuple of matplotlib figure and axes objects returned by create_plot().
return_type ('show', 'save', 'return') – The method for return the created plot. 'show' displays the figure, 'save' saves the figure without displaying, 'return' returns the axes for use with Matplotlib.
file_name (str, optional) – if return_type is “save”, the file name for your saved file. This can be any format supported by Matplotlib. If no file extension is included, .png is used by default. Default is 'vizent_plot_save'

Returns:

Matplotlib figure, if specified

Return type:

maptlotlib.figure or None

vizent.vizent_plot(x_values=None, y_values=None, color_values=None, shape_values=None, size_values=None, edge_start_points=None, edge_end_points=None, edge_colors=None, edge_frequencies=None, edge_widths=None, image_file=None, use_cartopy=False, cartopy_projection=None, extent=None, colormap='viridis', scale_diverges=None, shape='sine', shape_pos='sine', shape_neg='square', color_max=None, color_min=None, color_n=None, color_spread=None, shape_max=None, shape_min=None, shape_n=None, shape_spread=None, interval_type='closest', color_label='color', shape_label='shape', glyph_legend_title='glyphs', edge_striped_length=1, edge_length_type='units', edge_colormap='viridis', edge_style='middle', edge_color_max=None, edge_color_min=None, edge_color_n=None, edge_color_spread=None, edge_freq_max=None, edge_freq_min=None, edge_freq_n=None, edge_freq_spread=None, edge_interval_type='closest', edge_color_label='color', edge_frequency_label='frequency', edge_legend_title='lines', scale_dp=1, label_fontsize=None, scale_x=None, scale_y=None, use_image=None, image_type=None, colour_values=None, colour_max=None, colour_min=None, colour_n=None, colour_spread=None, colour_label=None, title=None, show_legend=None, x_label=None, y_label=None, show_axes=None, save=None, file_name=None, return_axes=None)#

Convenience function for implementing the vizent pipeline.

Parameters:

x_values (float or array-like, shape (n,), optional) – Positions of glyphs on the x-axis
y_values (float or array-like, shape (n,), optional) – Positions of glyphs on the y-axis
color_values (float or array-like, shape (n,), optional) – The values to be represented by the color of each glyph
shape_values (float or array-like, shape (n,), optional) – the list of values to be represented by the outer shape of each glyph
size_values (float or array-like, shape(n,), optional) – the list of values in points for the diameter of each glyph
edge_start_points (array-like, shape(n,2), optional) – (x,y) coordinates for each line origin
edge_end_points (array-like, shape(n,2), optional) – (x,y) coordinates for each line end point
edge_colors – The values to be represented by the color of each line.
edge_frequencies (float or array-like, shape (n,), optional) – The list of values to be represented by the central stripe frequency.
edge_widths (float or array-like, shape(n,), optional) – The list of values in points for the width of each line.
image_file (str, optional.) – filepath to a user-supplied image-file to be used as a background image for the plot.
use_cartopy (boolean, optional) – If True, use Cartopy to generate a map background. Must specify extent if used. Defaults to False.
extent – Axis limits or extent of coordinates for Cartopy. A list of four values in the form: [xmin, xmax, ymin, ymax].
colormap (matplotlib.colors.Colormap or str, optional) – the matplotlib colormap to be used for the glyphs. The default is viridis.
scale_diverges (boolean, optional) – If True, diverging sets of glyphs are used for positive and negative values. If not specified, your scale will diverge if both positive and negative values are included for the shape variable.
shape ('sine', 'saw', 'reverse_saw', 'square', 'triangular', 'concave', 'star'.) – Glyph shape design to use for non-divergent scales. Default 'sine'.
shape_pos ('sine', 'saw', 'reverse_saw', 'square', 'triangular', 'concave', 'star') – When using divergent scale, glyph shape design to use for positive values. Options as for shape. Default 'sine'.
shape_neg ('sine', 'saw', 'reverse_saw', 'square', 'triangular', 'concave', 'star') – When using divergent scale, glyph shape design to use for negative values. Options as for shape. Default 'square'.
color_max (float, optional) – The maximum color value in the glyph legend.
color_min (float, optional) – The minimum color value in the glyph legend.
color_n (int, optional) – The number of color values to show in the glyph legend.
color_spread (float, optional) – Range of color values in glyph legend. Only used if not specifying both max and min.
shape_max (float, optional) – The maximum shape value in the glyph legend.
shape_min (float, optional) – The minimum shape value in the glyph legend.
shape_n (int, optional) – The number of shape values to show in the glyph legend.
shape_spread (float, optional) – Range of shape values in glyph legend. Only used if not specifying both max and min.
color_label (str, optional) – The title for the color component of the glyph legend. Defaults to 'color'.
shape_label (str, optional) – The title for the shape component of the glyph legend. Defaults to 'shape'.
glyph_legend_title (str, optional) – The main title for the glyph legend. Defaults to 'glyphs'.
edge_striped_length (float, optional) – if using the style 'set_length', the length of the central stripe. Units determined by length_type. Defaults to 1.
edge_length_type (('units', 'pixels', 'proportion'), optional) – The units to be used for stripe length. 'units' uses axes units, 'pixels' uses the number of pixels and 'proportion' uses the proportion of the line.
edge_colormap (matplotlib.colors.Colormap or str, optional) – the matplotlib colormap to be used. Defaults to viridis.
edge_style (('middle', 'ends', 'source', 'destination'), optional.) – The length and positioning style of the striped area. 'middle' generates a striped area centred on the line/edge where with length of striped area 1/3 of edge length. 'ends' generates a striped area at each end of the line/edge with length of striped area 1/4 of total edge length. 'source' generates a striped area at the source of the line, 1/2 of the total edge length. 'destination' generates a striped area at the line destination, where the striped area is 1/2 of the total edge length. 'set_length' generates a striped area at the centre of the line, with the length specified by user via the edge_striped_length parameter, 'frequency' generates a striped area at the centre of the line, 1/3 edge length. Instead of a set number of stripes, this uses the number of stripes per unit length, matched to the legend. Defaults to 'middle'.
edge_color_max (float, optional) – The maximum color value in the legend.
edge_color_min (float, optional) – The minimum color value in the legend.
edge_color_n (int, optional) – The number of color values to show in the legend.
edge_color_spread (float, optional) – Range of color values in key. Only used if not specifying both max and min.
edge_freq_max (float, optional) – The maximum frequency value in the legend.
edge_freq_min (float, optional) – The minimum frequency value in the legend.
edge_freq_n (int, optional) – The number of frequency values to show in the legend.
edge_freq_spread (float, optional) – Range of frequency values in key. Only used if not specifying both max and min.
edge_color_label (str, optional) – The title for the color component of the legend. Defaults to 'color'.
edge_frequency_label (str, optional) – The title for the frequency component of the legend. Defaults to 'frequency'.
edge_legend_title (str, optional) – The main title for the glyph legend. Defaults to 'lines'.
scale_dp (int, optional) – The number of decimal places to round to for legend values. Defaults to 2.
label_fontsize – If set, will set all legend labels to this fontsize. Otherwise, the fontsize will be estimated automatically based on the length of the labels.

Returns:

Matplotlib figure

Return type:

maptlotlib.figure