API Documentation

plots

This is the most important part of nxviz - all of the plot objects are defined here.

class nxviz.plots.ArcPlot(graph, node_order=None, node_size=None, node_grouping=None, group_order='alphabetically', node_color=None, node_labels=None, edge_width=None, edge_color=None, data_types=None, nodeprops=None, edgeprops=None, node_label_color=False, group_label_position=None, group_label_color=False, fontsize=10, fontfamily='serif', **kwargs)[source]

Plotting object for ArcPlot.

compute_node_positions()[source]

Computes nodes positions.

Arranges nodes in a line starting at (x,y) = (0,0). Node radius is assumed to be equal to 0.5 units. Nodes are placed at integer locations.

draw()[source]

Draws the Plot to screen.

If there is a continuous datatype for the nodes, it will be reflected in self.sm being constructed (in compute_node_colors). It will then automatically add in a colorbar to the plot and scale the plot axes accordingly.

draw_edges()[source]

Renders edges to the figure.

draw_nodes()[source]

Draw nodes to screen.

class nxviz.plots.BasePlot(graph, node_order=None, node_size=None, node_grouping=None, group_order='alphabetically', node_color=None, node_labels=None, edge_width=None, edge_color=None, data_types=None, nodeprops=None, edgeprops=None, node_label_color=False, group_label_position=None, group_label_color=False, fontsize=10, fontfamily='serif', **kwargs)[source]

BasePlot: An extensible class for designing new network visualizations.

The BasePlot constructor takes in a NetworkX graph object, and a series of keyword arguments specifying how nodes and edges should be styled and ordered.

An optional data_types dictionary can be passed in to bypass data type inference.

Parameters:
  • graph (nx.Graph, nx.DiGraph, nx.MultiGraph, nx.MultiDiGraph) – A NetworkX graph object.
  • node_order (dict_key (often str)) – The node attribute on which to specify the coloring of nodes.
  • node_size (dict_key (often str)) – The node attribute on which to specify the size of nodes.
  • node_grouping (dict_key (often str)) – The node attribute on which to specify the grouping position of nodes.
  • group_order (dict_key (‘alphabetically’, ‘default’)) – The order in which the groups should be plotted.
  • group_label_position (bool) – The position of the group label.
  • group_label_position – Boolean, whether the group labels should be the same color as the nodes.
  • node_color (dict_key (often str)) – The node attribute on which to specify the colour of nodes.
  • node_labels (bool) – Boolean, whether to use node objects as labels or not.
  • edge_width – The edge attribute on which to specify the width of edges.
  • edge_color (dict_key (often str)) – The edge attribute on which to specify the colour of edges.
  • data_types (dict) – A mapping of node and edge data types that are stored.
  • nodeprops (dict) – A matplotlib-compatible props dictionary.
  • edgeprops (dict) – A matplotlib-compatible `props dictioanry.
  • fontsize (int) – A text property for editing size of labels in graph
  • fontfamily (string) – A text property to define font family. Valid inputs (‘serif’, ‘sans-serif’, ‘fantasy’, ‘monospace’).
check_data_types(data_types)[source]

Checks the data_types passed into the Plot constructor and makes sure that the values passed in belong to ‘ordinal’, ‘categorical’, or ‘continuous’.

Parameters:data_types (dict) – A dictionary mapping of data types.
compute_edge_colors()[source]

Compute the edge colors.

compute_edge_widths()[source]

Compute the edge widths.

compute_group_colors()[source]

Computes the group colors according to node colors

compute_group_label_positions()[source]

Computes the position of each group label according to the wanted position (“beginning”, “middle”, “end”)

Needs to be implemented for each plot type

compute_node_colors()[source]

Compute the node colors. Also computes the colorbar.

compute_node_label_positions()[source]

Computes the positions of each node’s labels on the plot. The horizontal and vertical alignment of the text varies according to the location.

Needs to be implemented for each plot type.

compute_node_positions()[source]

Computes the positions of each node on the plot.

Needs to be implemented for each plot type.

compute_node_sizes()[source]

Compute the node sizes.

draw()[source]

Draws the Plot to screen.

If there is a continuous datatype for the nodes, it will be reflected in self.sm being constructed (in compute_node_colors). It will then automatically add in a colorbar to the plot and scale the plot axes accordingly.

draw_edges()[source]

Renders the nodes to the plot or screen.

Needs to be implemented for each plot type.

draw_group_labels()[source]

Renders the group labels to the plot or screen.

Needs to be implemented for each plot type.

draw_nodes()[source]

Renders the nodes to the plot or screen.

Needs to be implemented for each plot type.

group_and_sort_nodes()[source]

Groups and then sorts the nodes according to the criteria passed into the Plot constructor.

class nxviz.plots.CircosPlot(graph, **kwargs)[source]

Plotting object for CircosPlot.

Accepts the following additional arguments apart from the ones in BasePlot:

Parameters:
  • node_label_layout (string) – which/whether (a) node layout is used, either ‘rotation’, ‘numbers’ or None
  • group_label_offset (float or int) – how much to offset the group labels, so that they are not overlapping with node labels.
compute_group_label_positions()[source]

Computes the x,y positions of the group labels.

compute_node_label_positions()[source]

Uses the get_cartesian function to compute the positions of each node label in the Circos plot.

This method is always called after the compute_node_positions method, so that the plot_radius is pre-computed. This will also add a new attribute, node_label_rotation to the object which contains the rotation angles for each of the nodes. Together with the node coordinates this can be used to add additional annotations with rotated text.

compute_node_positions()[source]

Uses the get_cartesian function to compute the positions of each node in the Circos plot.

draw_edges()[source]

Renders edges to the figure.

draw_group_labels()[source]

Renders group labels to the figure.

draw_nodes()[source]

Renders nodes to the figure.

init_node_label_meta()[source]

This function ensures that self.node_label_coords exist with the correct keys and empty entries This function should not be called by the user

static nonzero_sign(xy)[source]

A sign function that won’t return 0

store_node_label_meta(x, y, tx, ty, rot)[source]

This function stored coordinates-related metadate for a node This function should not be called by the user

Parameters:
  • x (np.float64) – x location of node label or number
  • y (np.float64) – y location of node label or number
  • tx (np.float64) – text location x of node label (numbers)
  • ty (np.float64) – text location y of node label (numbers)
  • rot (float) – rotation angle of the text (rotation)
class nxviz.plots.GeoPlot(graph, node_lat: str, node_lon: str, backend: str = 'matplotlib', **kwargs)[source]

Plotting object for GeoPlot.

User only has to specify the keyword arguments that specify the longitude and latittude of a node.

compute_node_positions()[source]

Extracts the node positions based on the specified longitude and latitude keyword arguments.

draw()[source]

Draws the Plot to screen.

If there is a continuous datatype for the nodes, it will be reflected in self.sm being constructed (in compute_node_colors). It will then automatically add in a colorbar to the plot and scale the plot axes accordingly.

draw_edges()[source]

Draws edges to screen.

draw_nodes()[source]

Draws nodes to the screen.

GeoPlot is the first plot kind to support an Altair backend in addition to the usual matplotlib backend.

class nxviz.plots.MatrixPlot(graph, node_order=None, node_size=None, node_grouping=None, node_color=None, edge_width=None, edge_color=None, data_types=None, nodeprops=None, edgeprops=None)[source]

Plotting object for the MatrixPlot.

draw()[source]

Draws the plot to screen.

Note to self: Do NOT call super(MatrixPlot, self).draw(); the underlying logic for drawing here is completely different from other plots, and as such necessitates a different implementation.

io

nxviz.io.graph_from_dataframe(dataframe, threshold_by_percent_unique=0.1, threshold_by_count_unique=None, node_id_columns=[], node_property_columns=[], edge_property_columns=[], node_type_key='type', edge_type_key='type', collapse_edges=True, edge_agg_key='weight')[source]

Build an undirected graph from a pandas dataframe.

This function attempts to infer which cells should become nodes based on either:

  1. what percentage of the column are unique values (defaults to 10%)
  2. an explicit count of unique values (i.e. any column with 7 unique values or less)
  3. an explicit list of column keys (i.e. [‘employee_id’, ‘location_code’])

Column headers are preserved as node and edge ‘types’. By default, this is stored using the key ‘type’ which is used by some graph import processes but can be reconfigured.

This function uses a MultiGraph structure during the build phase so that it is possible to make multiple connections between nodes. By default, at the end of the build phase, the MultiGraph is converted to a Graph and the count of edges between each node-pair is written as a ‘weight’ property.

Parameters:
  • dataframe (pandas.DataFrame) – A pandas dataframe containing the data to be converted into a graph.
  • threshold_by_percent_unique (float) – A percent value used to determine whether a column should be used to generate nodes based on its cardinality (i.e. in a dataframe with 100 rows, treat any column with 10 or less unique values as a node)
  • threshold_by_count_unique (int) – A numeric value used to determine whether a column should be used to generate nodes based on its cardinality (i.e. if 7 is supplied, treat any column with 7 or less unique values as a node) - supplying a value will take priority over percent_unique
  • node_id_columns (list) – A list of column headers to use for generating nodes. Suppyling any value will take precedence over threshold_by_percent_unique or threshold_by_count_unique. Note: this can cause the size of the graph to expand significantly since every unique value in a column will become a node.
  • node_property_columns (list) – A list of column headers to use for generating properties of nodes. These can include the same column headers used for the node id.
  • edge_property_columns (list) – A list of column headers to use for generating properties of edges.
  • node_type_key (str) – A string that sets the key will be used to preserve the column name as node property (this is useful for importing networkx graphs to databases that distinguish between node ‘types’ or for visually encoding those types in plots).
  • edge_type_key (str) – A string that sets the key will be used to keep track of edge relationships an ‘types’ (this is useful for importing networkx graphs to databases that distinguish between edge’types’ or for visually encoding those types in plots). Edge type values are automatically set to <node_a_id>_<node_b_id>.
  • collapse_edges (bool) – Graphs are instantiated as a ‘MultiGraph’ (allow multiple edges between nodes) and then collapsed into a ‘Graph’ which only has a single edge between any two nodes. Information is preserved by aggregating the count of those edges as a ‘weight’ value. Set this value to False to return the MultiGraph. Note: this can cause the size of the graph to expand significantly since each row can potentially have n! edges where n is the number of columns in the dataframe.
  • edge_agg_key (str) – A string that sets the key the edge count will be assigned to when edges are aggregated.
Returns:

A networkx Graph (or MultiGraph if collapse_edges is set to False).

geometry

Geometry functions are declared here.

Utility geometry functions that can help with drawing to screen.

nxviz.geometry.circos_radius(n_nodes, node_r)[source]

Automatically computes the origin-to-node centre radius of the Circos plot using the triangle equality sine rule.

a / sin(A) = b / sin(B) = c / sin(C)

Parameters:
  • n_nodes (int) – the number of nodes in the plot.
  • node_r (float) – the radius of each node.
Returns:

Origin-to-node centre radius.

nxviz.geometry.correct_negative_angle(angle)[source]

Corrects a negative angle to a positive one.

Parameters:angle (float) – The angle in radians.
Returns:angle, corrected to be positively-valued.
nxviz.geometry.get_cartesian(r, theta)[source]

Returns the cartesian (x,y) coordinates of (r, theta).

Parameters:
  • r (int, float.) – Real-valued radius.
  • theta (int, float.) – Angle
Returns:

to_cartesian(r, theta)

nxviz.geometry.group_theta(node_length, node_idx)[source]

Returns an angle corresponding to a node of interest.

Intended to be used for placing node group labels at the correct spot.

Parameters:
  • node_length (float) – total number of nodes in the graph.
  • node_idx (int) – the index of the node of interest.
Returns:

theta – the angle of the node of interest in radians.

nxviz.geometry.node_theta(nodelist, node)[source]

Maps node to Angle.

Parameters:
  • nodelist (list.) – Nodelist from the graph.
  • node – The node of interest. Must be in the nodelist.
Returns:

theta – the angle of the node in radians.

nxviz.geometry.text_alignment(x, y)[source]

Align text labels based on the x- and y-axis coordinate values.

This function is used for computing the appropriate alignment of the text label.

For example, if the text is on the “right” side of the plot, we want it to be left-aligned. If the text is on the “top” side of the plot, we want it to be bottom-aligned.

Parameters:y (x,) – (int or float) x- and y-axis coordinate respectively.
Returns:A 2-tuple of strings, the horizontal and vertical alignments respectively.

utils

nxviz.utils.infer_data_type(data_container)[source]

For a given container of data, infer the type of data as one of continuous, categorical, or ordinal.

For now, it is a one-to-one mapping as such:

  • str: categorical
  • int: ordinal
  • float: continuous

There may be better ways that are not currently implemented below. For example, with a list of numbers, we can check whether the number of unique entries is less than or equal to 12, but has over 10000+ entries. This would be a good candidate for floats being categorical.

Parameters:data_container (iterable) – A generic container of data points.
nxviz.utils.is_data_diverging(data_container)[source]

We want to use this to check whether the data are diverging or not.

This is a simple check, can be made much more sophisticated.

Parameters:data_container (iterable) – A generic container of data points.
nxviz.utils.is_data_homogenous(data_container)[source]

Checks that all of the data in the container are of the same Python data type. This function is called in every other function below, and as such need not necessarily be called.

Parameters:data_container (iterable) – A generic container of data points.
nxviz.utils.is_groupable(data_container)[source]

Returns whether the data container is a “groupable” container or not.

By “groupable”, we mean it is a ‘categorical’ or ‘ordinal’ variable.

Parameters:data_container (iterable) – A generic container of data points.
nxviz.utils.items_in_groups(data_container)[source]

Returns discrete groups present in a data container and the number items per group.

Parameters:data_container (iterable) – A generic container of data points.
nxviz.utils.n_group_colorpallet(n)[source]

If more then 8 categorical groups of nodes or edges this function creats the matching color_palette

nxviz.utils.num_discrete_groups(data_container)[source]

Returns the number of discrete groups present in a data container.

Parameters:data_container (iterable) – A generic container of data points.
nxviz.utils.to_pandas_edges(G, x_kw, y_kw, **kwargs)[source]

Convert Graph edges to pandas DataFrame that’s readable to Altair.

nxviz.utils.to_pandas_nodes(G)[source]

Convert nodes in the graph into a pandas DataFrame.