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.


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 matplotlibcompatible props dictionary.
 edgeprops (dict) – A matplotlibcompatible `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’, ‘sansserif’, ‘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_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_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.

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.

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_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 precomputed. 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.

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

store_node_label_meta
(x, y, tx, ty, rot)[source]¶ This function stored coordinatesrelated 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.

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:
 what percentage of the column are unique values (defaults to 10%)
 an explicit count of unique values (i.e. any column with 7 unique values or less)
 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 nodepair 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 origintonode 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: Origintonode 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 positivelyvalued.

nxviz.geometry.
get_cartesian
(r, theta)[source]¶ Returns the cartesian (x,y) coordinates of (r, theta).
Parameters:  r (int, float.) – Realvalued 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 yaxis 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 leftaligned. If the text is on the “top” side of the plot, we want it to be bottomaligned.
Parameters: y (x,) – (int or float) x and yaxis coordinate respectively. Returns: A 2tuple 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 onetoone 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.