nxviz Documentation Release 0.3 Eric J. Ma Mar 11, 2019
Contents 1 Installation 3 1.1 Stable release............................................... 3 1.2 From sources............................................... 3 2 Usage 5 3 Contributing 7 3.1 Types of Contributions.......................................... 7 3.2 Get Started!................................................ 8 3.3 Pull Request Guidelines......................................... 9 3.4 Tips.................................................... 9 4 Credits 11 4.1 Development Lead............................................ 11 4.2 Contributors............................................... 11 5 History 13 5.1 0.3.7 (2018-XX-XX)........................................... 13 5.2 0.3.6 (2018-02-20)............................................ 13 5.3 0.3.5 (2018-01-20)............................................ 13 5.4 0.3.2 (2017-09-18)............................................ 13 5.5 0.1.0 (2016-07-15)............................................ 13 6 API Documentation 15 6.1 plots................................................... 15 6.2 io..................................................... 19 6.3 geometry................................................. 20 6.4 utils.................................................... 21 7 Indices and tables 23 Python Module Index 25 i
ii
# nxviz nxviz is a graph visualization package for NetworkX. With nxviz, you can create beautiful graph visualizations by a declarative API. Here s an example. `python # Assume we have a professional network of physicians belonging to hospitals. c = CircosPlot(G, node_color='affiliation', node_grouping='affiliation') c.draw() plt.show() # only needed in scripts ` This is free software distributed under the MIT License. ## Installation We recommend using [conda]. ` $ conda install -c conda-forge nxviz ` Alternatively, it is also available on [PyPI]. ` $ pip install nxviz ` [conda]: https://www.anaconda.com/download/ [PyPI]: https://pypi.python.org/pypi/nxviz ## Requirements For requirements, consult the requirements.txt file in the GitHub repository. As a matter of practice, nxviz development will try (where relevant) to take advantage of the latest Python features. As of 18 September 2017, this means Python 3.6 is the officially supported version, as there are places where we use f-string formatting to simplify logging and debugging. ## Features Declarative API. Works with NetworkX, one of the more popular graph libraries in Python. Can build NetworkX graphs from a pandas DataFrame ## Feature Requests If you have a feature request, please post it as an issue on the GitHub repository [issue tracker][issue]. Even better, put in a [PR] for it! I am more than happy to guide you through the codebase so that you can put in a contribution to the codebase - and I ll give you a digital nxviz contributor badge that you can put on your personal website, as a way of saying thanks! Because nxviz is currently maintained by volunteers and has no fiscal support, any feature requests will be prioritized according to what maintainers encounter as a need in our day-to-day jobs. Please temper expectations accordingly. [issue]: https://github.com/ericmjl/nxviz/issues [PR]: https://github.com/ericmjl/nxviz/pulls ## Credits This package was created with [Cookiecutter] and the [audreyr/cookiecutter-pypackage][pypkg] project template. [Cookiecutter]: https://github.com/audreyr/cookiecutter [pypkg]: https://github.com/audreyr/cookiecutter-pypackage Contents 1
2 Contents
CHAPTER 1 Installation 1.1 Stable release To install nxviz, run this command in your terminal: $ pip install nxviz This is the preferred method to install nxviz, as it will always install the most recent stable release. If you don t have pip installed, this Python installation guide can guide you through the process. 1.2 From sources The sources for nxviz can be downloaded from the Github repo. You can either clone the public repository: $ git clone git://github.com/ericmjl/nxviz Or download the tarball: $ curl -OL https://github.com/ericmjl/nxviz/tarball/master Once you have a copy of the source, you can install it with: $ python setup.py install 3
4 Chapter 1. Installation
CHAPTER 2 Usage To use nxviz in a project: from nxviz.plots import CircosPlot # Assume we have a professional network of physicians belonging # to hospitals. c = CircosPlot(G, node_color='affiliation', node_grouping='affiliation') c.draw() plt.show() # only needed in scripts 5
6 Chapter 2. Usage
CHAPTER 3 Contributing Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. You can contribute in many ways: 3.1 Types of Contributions 3.1.1 Report Bugs Report bugs at https://github.com/ericmjl/nxviz/issues. If you are reporting a bug, please include: Your operating system name and version. Any details about your local setup that might be helpful in troubleshooting. Detailed steps to reproduce the bug. 3.1.2 Fix Bugs Look through the GitHub issues for bugs. Anything tagged with bug and help wanted is open to whoever wants to implement it. 3.1.3 Implement Features Look through the GitHub issues for features. Anything tagged with enhancement and help wanted is open to whoever wants to implement it. 7
3.1.4 Write Documentation nxviz could always use more documentation, whether as part of the official nxviz docs, in docstrings, or even on the web in blog posts, articles, and such. 3.1.5 Submit Feedback The best way to send feedback is to file an issue at https://github.com/ericmjl/nxviz/issues. If you are proposing a feature: Explain in detail how it would work. Keep the scope as narrow as possible, to make it easier to implement. Remember that this is a volunteer-driven project, and that contributions are welcome :) 3.2 Get Started! Ready to contribute? Here s how to set up nxviz for local development. 1. Fork the nxviz repo on GitHub. 2. Clone your fork locally: $ git clone git@github.com:your_name_here/nxviz.git 3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development: $ mkvirtualenv nxviz $ cd nxviz/ $ python setup.py develop 4. (Optionally) Build the docs: $ cd docs/ $ make html # docs will found in _build/html/. Open `index.html` to view the docs; macos users can do `open _build/html/index.html` to open the docs in your default browser. 4. Create a branch for local development: $ git checkout -b name-of-your-bugfix-or-feature Now you can make your changes locally. 5. When you re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox: $ flake8 nxviz tests $ python setup.py test or py.test $ tox To get flake8 and tox, just pip install them into your virtualenv. 6. Commit your changes and push your branch to GitHub: 8 Chapter 3. Contributing
$ git add. $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature 7. Submit a pull request through the GitHub website. 3.3 Pull Request Guidelines Before you submit a pull request, check that it meets these guidelines: 1. The pull request should include tests. 2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. 3. The pull request should work for Python 3.4 and 3.5. Check https://travis-ci.org/ericmjl/nxviz/pull_requests and make sure that the tests pass for all supported Python versions. 3.4 Tips To run a subset of tests: $ py.test tests.test_nxviz 3.3. Pull Request Guidelines 9
10 Chapter 3. Contributing
CHAPTER 4 Credits 4.1 Development Lead Eric J. Ma <ericmajinglong (at) gmail.com> 4.2 Contributors Nora Kassner <nora.kassner (at) t-online.de> Christian Diener <mail (at) cdiener.com> Thijs Hermans <hermansthijs91 (at) gmail.com> 18. (m) Keelan Downton <keelan.downton (at) gmail.com> Maximilian T. Strauss <straussmaximilian (at) gmail.com> Brian Cajes @bcajes Ashutosh Chandra @ashu16993 11
12 Chapter 4. Credits
CHAPTER 5 History 5.1 0.3.7 (2018-XX-XX) Node labels in CircosPlot can now be rotated with the rotate_labels argument. 5.2 0.3.6 (2018-02-20) Implemented edge colours, thanks to @noragak. 5.3 0.3.5 (2018-01-20) Disabled health checks on certain tests. Added ability to configure plot size. Added docs on preparing a new release. Updated dependencies. 5.4 0.3.2 (2017-09-18) All plots except for HivePlot are implemented. Implemented auto-colorbar for plots that have continuous node colors. 5.5 0.1.0 (2016-07-15) First release on PyPI. 13
14 Chapter 5. History
CHAPTER 6 API Documentation 6.1 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) Plotting object for ArcPlot. compute_node_positions() 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() 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() Renders edges to the figure. draw_nodes() Draw nodes to screen. 15
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) 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) 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() Compute the edge colors. 16 Chapter 6. API Documentation
compute_edge_widths() Compute the edge widths. compute_group_colors() Computes the group colors according to node colors compute_group_label_positions() 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() Compute the node colors. Also computes the colorbar. compute_node_label_positions() 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() Computes the positions of each node on the plot. Needs to be implemented for each plot type. draw() 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() Renders the nodes to the plot or screen. Needs to be implemented for each plot type. draw_group_labels() Renders the group labels to the plot or screen. Needs to be implemented for each plot type. draw_nodes() Renders the nodes to the plot or screen. Needs to be implemented for each plot type. group_and_sort_nodes() Groups and then sorts the nodes according to the criteria passed into the Plot constructor. class nxviz.plots.circosplot(graph, **kwargs) 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 compute_group_label_positions() Computes the x,y positions of the group labels. compute_node_label_positions() Uses the get_cartesian function to compute the positions of each node label in the Circos plot. 6.1. plots 17
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() Uses the get_cartesian function to compute the positions of each node in the Circos plot. draw_edges() Renders edges to the figure. draw_group_labels() Renders group labels to the figure. draw_nodes() Renders nodes to the figure. init_node_label_meta() 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) A sign function that won t return 0 store_node_label_meta(x, y, tx, ty, rot) 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) Plotting object for GeoPlot. User only has to specify the keyword arguments that specify the longitude and latittude of a node. compute_node_positions() Extracts the node positions based on the specified longitude and latitude keyword arguments. draw() 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() Draws edges to screen. draw_nodes() Draws nodes to the screen. GeoPlot is the first plot kind to support an Altair backend in addition to the usual matplotlib backend. 18 Chapter 6. API Documentation
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) Plotting object for the MatrixPlot. draw() 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. 6.2 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 ) 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. 6.2. io 19
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). 6.3 geometry Geometry functions are declared here. Utility geometry functions that can help with drawing to screen. nxviz.geometry.circos_radius(n_nodes, node_r) 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) 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) 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) Returns an angle corresponding to a node of interest. Intended to be used for placing node group labels at the correct spot. 20 Chapter 6. API Documentation
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) 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) 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. 6.4 utils nxviz.utils.infer_data_type(data_container) 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) 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) 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. 6.4. utils 21
nxviz.utils.is_groupable(data_container) 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) 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) If more then 8 categorical groups of nodes or edges this function creats the matching color_palette nxviz.utils.num_discrete_groups(data_container) 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) Convert Graph edges to pandas DataFrame that s readable to Altair. nxviz.utils.to_pandas_nodes(g) Convert nodes in the graph into a pandas DataFrame. 22 Chapter 6. API Documentation
CHAPTER 7 Indices and tables genindex modindex search 23
24 Chapter 7. Indices and tables
Python Module Index n nxviz.geometry, 20 nxviz.io, 19 nxviz.plots, 15 nxviz.utils, 21 25
26 Python Module Index
Index A ArcPlot (class in nxviz.plots), 15 B BasePlot (class in nxviz.plots), 15 C check_data_types() (nxviz.plots.baseplot method), 16 circos_radius() (in module nxviz.geometry), 20 CircosPlot (class in nxviz.plots), 17 compute_edge_colors() (nxviz.plots.baseplot method), 16 compute_edge_widths() (nxviz.plots.baseplot method), 16 compute_group_colors() (nxviz.plots.baseplot method), 17 compute_group_label_positions() (nxviz.plots.baseplot method), 17 compute_group_label_positions() (nxviz.plots.circosplot method), 17 compute_node_colors() (nxviz.plots.baseplot method), 17 compute_node_label_positions() (nxviz.plots.baseplot method), 17 compute_node_label_positions() (nxviz.plots.circosplot method), 17 compute_node_positions() (nxviz.plots.arcplot method), 15 compute_node_positions() (nxviz.plots.baseplot method), 17 compute_node_positions() (nxviz.plots.circosplot method), 18 compute_node_positions() (nxviz.plots.geoplot method), 18 correct_negative_angle() (in module nxviz.geometry), 20 D draw() (nxviz.plots.arcplot method), 15 draw() (nxviz.plots.baseplot method), 17 draw() (nxviz.plots.geoplot method), 18 draw() (nxviz.plots.matrixplot method), 19 draw_edges() (nxviz.plots.arcplot method), 15 draw_edges() (nxviz.plots.baseplot method), 17 draw_edges() (nxviz.plots.circosplot method), 18 draw_edges() (nxviz.plots.geoplot method), 18 draw_group_labels() (nxviz.plots.baseplot method), 17 draw_group_labels() (nxviz.plots.circosplot method), 18 draw_nodes() (nxviz.plots.arcplot method), 15 draw_nodes() (nxviz.plots.baseplot method), 17 draw_nodes() (nxviz.plots.circosplot method), 18 draw_nodes() (nxviz.plots.geoplot method), 18 G GeoPlot (class in nxviz.plots), 18 get_cartesian() (in module nxviz.geometry), 20 graph_from_dataframe() (in module nxviz.io), 19 group_and_sort_nodes() (nxviz.plots.baseplot method), 17 group_theta() (in module nxviz.geometry), 20 I infer_data_type() (in module nxviz.utils), 21 init_node_label_meta() (nxviz.plots.circosplot method), 18 is_data_diverging() (in module nxviz.utils), 21 is_data_homogenous() (in module nxviz.utils), 21 is_groupable() (in module nxviz.utils), 21 items_in_groups() (in module nxviz.utils), 22 M MatrixPlot (class in nxviz.plots), 18 N n_group_colorpallet() (in module nxviz.utils), 22 node_theta() (in module nxviz.geometry), 21 nonzero_sign() (nxviz.plots.circosplot static method), 18 num_discrete_groups() (in module nxviz.utils), 22 nxviz.geometry (module), 20 27
nxviz.io (module), 19 nxviz.plots (module), 15 nxviz.utils (module), 21 S store_node_label_meta() method), 18 (nxviz.plots.circosplot T text_alignment() (in module nxviz.geometry), 21 to_pandas_edges() (in module nxviz.utils), 22 to_pandas_nodes() (in module nxviz.utils), 22 28 Index