Addon:NetworkChart
This is a Third-party Addon. Please use carefully on data that is backed up, and help make it better by reporting any comments or problems to the author, or issues to the bug tracker |
Long chart creation times Generating a chart of every individual in a very large database can lead to long chart generation times (See Performance). Of course, subsets can be selected greatly reducing the chart generation times (See Trim and Highlight). |
Slight Variations in Graph Layouts Generated Network Chart graphs may change slightly after Gramps restarts. This is due to the nondeterministic nature of the Graphviz memory allocation method used in the dot layout engine. |
Network Chart is a Web Pages Report addon for Gramps that can:
- Generate a single graph showing connectivity between individuals
- Has clickable nodes (individuals) that contain a hyperlink for a visual index
- Display connectivity paths and highlight them
The default output is a Scalable Vector Graphics (SVG) file that can be viewed in a browser. Network Chart requires the following prerequisites; the python networkx module to assist in selecting what to display and Graphviz via the pygraphviz module to generate the chart.
Contents
Usage
To start the Network Chart addon use the following menu option Reports > Web Pages > Network Chart...
Make sure you have installed the required prerequisites.
Main
The Shakespeare database used for the examples was downloaded from the http://genealogyoflife.com/ (Gone, try [1]) website. |
The Main preferences tab (see image on left) controls the output Filename, Folder, File Type and chart title. The filename defaults to the database name + '_network' with '.svg'(default) added automatically on output. The Chart Title defaults to the database name and the folder to the top level user default home. Once an entry is changed it will be remembered and used for the next time as well. Clearing the entry will set it back to default. Additionally, name and date formats for the chart can be modified using the Gramps available formatting. The output File Type can be changed to a PDF. The PDF will not have URL links but everything else will display the same as the SVG.
Graph style menu selects the type of connectors with choices being Orthogonal, Straight, and Curved. In the example default output shown on the right, the default orthogonal option was selected resulting in straight connectors with right angles. Graphs with over 1500 people should probably use the Curved or Straight options with noticeable reduction in the time needed for graph generation.
Graph Direction controls which of the four different orientations to use.
URL Style selects one of Database, Dynamic, Static, or None (Don't include). This option selects what hyperlink will be used for individual nodes when the SVG chart is viewed from a browser. The Database option will select the primary URL from the database if one is available or none if it is not. Dynamic will use the URL Prefix, Suffix from the next line in the Menu and the GrampsID of the node. The Example Default Output chart shown includes dynamic URL's. For example, Henry Webb in the database has GrampsID = I0125. So the URL for that node will have the prefix of ' https://mywebsite.com/home/ ' and the suffix '.html' yielding a node with a link to ' https://mywebsite.com/home/I0125.html '. The dynamic URL changes for every node. A static URL will use only the URL Prefix and the Don't Include URL or None will not place any link in the nodes.
The font selection is straightforward. Obtain the name of the font that you wish to use and type it in the entry box. The only requirement is that the font already be installed on your system. If the font is not found then a default font will be used. This is a silent operation and will not warn on a font not found. When the SVG graph is generated that font will be identified for use, however, if someone viewing the chart does not have the same font installed they will see their default font instead. (Embedding fonts in SVGs or making them a local access is possible but not available in this addon.) The default font is White Rabbit by Matthew Welch which is an extremely readable font. It can be obtained from https://www.fontsquirrel.com/fonts/white-rabbit and the license found at http://www.squaregear.net/fonts/license.shtml .
The Spacing option controls the space between "generations" of nodes. It can be anywhere from 0.1 - 5.0 inches. Finally, you can use "Different node shape/edges for gender" to controls the box shapes and makes the Male and Female box shapes different, by default this selection is turned off.
Color
The Color preferences tab controls most of the colors on the chart. The Network Chart SVG background is transparent so the background color you see will be the default background color of your browser or if the SVG was embedded in a webpage with a background image you will see that image below the Network Chart SVG. The node backgrounds for Male, Female, and Other can be changed. An alpha transparency is used for the individual node backgrounds. Setting this to 0 will make the node background completely transparent. Setting it to 255 will make it completely solid (opaque).
Connector lines are just that, the connecting lines from node to node for a family connection or marriage. The Highlight connector line is used for a highlighted path as discussed in the Highlight Menu section. The Trim box edge is used on nodes in the graph that have been "trimmed" as discussed in the Trim Menu section. Finally, all node background colors can be set to none with the Remove Color Backgrounds option.
Privacy
The Privacy preferences tab allows dates for birth and marriage to be made vague. All individuals that have a valid date for either a birth or marriage can have that date rounded to the nearest decade after the year to start entered. Additionally, middle names can be changed to just show initials. Finally, private records for individuals can be included or not. If not, the individual node will contain the words "Private Record" for all those individuals marked private in Gramps.
Trim
The Trim preferences tab allows "trimming" of the database to display less individuals in the Network Chart. The Trim Descendants option trims all descendants "below" the selected individuals. The Trim Ancestors option attempts to trim all ancestors "above" the selected individuals. Individuals by marriage will also be removed depending on their location in the network relative to the person trimmed. Both options allow entry of multiple people. The Trim Menu image shows the selection of individual I0118 to trim descendants and I0111 to trim ancestors. The result is shown on the right in the Trim Example 1. Note the nodes of the individuals selected on the trim tab are bordered with a red dashed trim.
Trim Menu Example 2 shows the selection of additional individuals to trim. However, this example will generate "orphans" or individuals with no connections as a result of the trimming operation. This is shown in Trim Example 2. Note the three isolated individuals in the top right corner including one of the individuals selected in the trim menu.
The Trim Groups option will trim smaller groups/trees or individuals that are disconnected. You must enter the minimum number of individuals in a group/tree to display. For databases with more than 1500 individuals this option is required and the minimum number is set to 2. This will force all disconnected single individuals to be removed from the graph. Selecting a number greater than the largest group/tree will return only the largest tree or those trees that are equal in size. For this example the Trim Groups has been selected with a size of 2. The result removes the isolated individuals from the graph as shown in the Trim Example 3 chart.
Highlight
The Highlight preferences tab. The Highlight Menu highlights paths and individuals in the database. The Highlight Path option choices are "Direct" or "Any". The Direct option will attempt to find a direct path between the two individuals selected and highlight that path. The Any option will attempt to find any path between the two selected individuals and highlight that path. The example shows Highlight Path Direct between the two individuals with the result shown in Highlight Example 1.
The Show Path Only will display only the path found and remove all others from the chart. The choices are "Direct" or "Any". The Direct option will attempt to find a direct path between the two individuals selected and display only that path. The Any option will attempt to find any path between the two selected individuals and display only that path. The example shows the Show Only Path option with Direct selected. The result is shown in Highlight Example 2.
The Center Person option allows one to select a center person for the chart and radius that will isolate the included nodes to just that selected person and anyone within the radius. The radius is the maximum allowable steps or edges between the center person and anyone else in the graph. All others outside of the maximum steps or edges will not be shown. Any connection via parent, child, or marriage counts as a step or edge.
Config
The Config preferences tab allows modification of some basic functionality of the Network Chart addon.
The Name format can be changed.
The GrampsID in a database can change for an individual, however, the underlying database handle for an individual should never change. Thus the Use Database Handle option can be used for the Dynamic URL generation on the main menu to replace the GrampsID with the database handle. This is typically much longer than the GrampsID.
The confirm overwrite option allows one to stop the overwrite warnings and just overwrite the file.
The Translation option allows the selection of the Language.
Finally the date format allows you to change the format.
Prerequisites
Network Chart requires the python networkx module to assist in selecting what to display and Graphviz via the pygraphviz module to generate the chart.
Requires the following to be installed (type pip3 if system default is still python 2):
networkx version 1.x Note that Network Graph Report Fails when used with with networkx v2.x See:11471)
pip install networkx
or
pip3 install networkx
To get "libcgraph" for pygraphviz you first need to install the development package of graphviz eg:
apt install graphviz-dev or dnf install graphviz-devel
then run:
pip install pygraphviz
or
pip3 install pygraphviz
Troubleshooting[2]
You can check if networkx and pygraphviz installed correctly by starting python (type python3 if system default is still python 2) and attempt to import both packages eg:
python3
import networkx
If no error occurs then networkx is fine
then try
import pygraphviz
If no error occurs then pygraphviz is fine
If you receive any error, correct the issue and test again.
Performance
Network Chart was intended for smaller databases or subsets and is extremely fast for charts with less than 1500 nodes. However, it can generate very large graphs in reasonable time and should be adequate for those large databases that do not change frequently. Some optimizations for large databases are done automatically. The Trim Groups selection is one. Another method to greatly decrease the time to generate a chart on a large database is to select Straight or Curved for the Graph Style on the Main preferences tab. Reducing the number of nodes to graph via Trim and Highlight tabs will reduce graph generation times. For example, if your database contains 65535 individuals and you trim or highlight to plot only 8191 individuals, it would take closer to 20 seconds to generate the chart (based on the following table). Some performance data is shown below for an Intel(R) Core(TM) i7-2600K CPU @ 3.40GHz with 16GB of RAM and an SSD for storage.
Network Chart Performance (times are HH:MM:SS) | |||||
---|---|---|---|---|---|
Data File | # Individuals | Graph Style | Trim Groups | SVG File Size | Time to Generate |
d03 | 124032 | Curved | 2 | 107.2MB | 00:51:04 |
ENFAN16 | 65535 | Curved | 2 | 95.6MB | 00:34:47 |
ENFAN15 | 32767 | Curved | 2 | 47.8MB | 00:07:42 |
ENFAN14 | 16383 | Curved | 2 | 23.8MB | 00:01:23 |
ENFAN13 | 8191 | Curved | 2 | 11.9MB | 00:00:20 |
Royals ged | 3010 | Orthogonal | Not Used | 4.4MB | 00:00:07 |
Issues
- 11900 [MacOS installers] Add prerequistes NetworkChart [Wontfix]MacOS use: MacPorts
- 10197 Network Chart report Running report on second Family tree shows first family trees chosen Gramps id.
- 11471 Network Graph Report Fails with networkx v2.x
- Help button goes incorrectly to [3] instead of here.