View on GitHub

pedigreejs

A web tool for building and displaying pedigrees.


Overview

pedigreejs is a JavaScript library used to draw family trees using standard pedigree nomenclature. It uses the JavaScript d3 library to layout the hierarchical structure and draw the individual nodes as a SVG image. The size of the SVG can be configured as well as the colour codes used to denote disease. It can be used to build the pedigree structure or load in an existing data set. To assist visualisation and building of larger pedigrees a full screen mode is provided.

Browser local storage is used to maintain a history of the steps in building a pedigree structure. So that at each step of the pedigree building process it can be undone to return to previous versions.

See the developer documentation for more details about setting up pedigreejs.

A demonstration page is available here. Other example pages and configurations are given below:

Building Pedigrees

Individuals can be added to the pedigree by placing the mouse over an individual to reveal the widgets used for editing and adding a partner (two people with at least one child), parents , a sibling , or a child . Options are given to add male , female , unknown , dizygotic (fraternal) twin or monozygotic (identical) twin .

If the 'edit' parameter is set in the configuration of pedigreejs then the widget is also displayed. When this widget is clicked it opens an editor dialog of the attributes associated for the individual. A default editor is provided that can be overridden and customised.

Half siblings can be added by creating a new partner (with ) for the parent in common to the siblings. Consanguineous partners can be created between individual's at the same or different levels in the pedigree tree, e.g. cousins. This is done by placing the mouse over one of the partners and clicking and dragging the triple dashed line widget handle in the direction of their new partner.

There are 'undo' , 'redo' and 'reset' buttons at the top and a button to enable full screen editing .

Loading and Saving Pedigree Data

The pedigree can be saved out and loaded back in. Support is given to loading CanRisk files, and PED files (see example 4).

Configuration and Integration Notes

The following parameters can be used to configure pedigreejs. Please also see the developer notes for more details about programmatically interacting with pedigreejs. The important parameter to configure is 'targetDiv' which defines the HTML div used for drawing the pedigree. Default parameters are provided which are documented below. There is a configuration parameter 'edit' which can take a function, so that a customised editor can be written to view and edit an individual's attributes (e.g. name, sex). Alternatively if 'edit' is set to true a default dialog will be displayed showing the individual's attributes.

	var opts = {
		'targetDiv': 'pedigree',
		'btn_target': 'pedigree_history',
		'width': 450,
		'height': 320,
		'symbol_size': 35,
		'store_type': 'array',
		'diseases': [
			{'type': 'breast_cancer', 'colour': '#F68F35'},
			{'type': 'ovarian_cancer', 'colour': '#4DAA4D'},
			{'type': 'pancreatic_cancer', 'colour': '#4289BA'},
			{'type': 'prostate_cancer', 'colour': '#D5494A'}],
		labels: ['age', 'yob'],
		font_size: '.75em',
		font_family: 'Helvetica',
		font_weight: 700,
		'DEBUG': (pedigree_util.urlParam('debug') === null ? false : true)
	};
	var local_dataset = pedcache.current(opts);
	if (local_dataset !== undefined && local_dataset !== null) {
		opts.dataset = local_dataset;
	} else {
		opts.dataset = dataset;
	}
	opts= ptree.build(opts);

Options

targetDiv
This is the id of the HTML div used for drawing the pedigree, e.g. 'pedigree_edit'.
btn_target
This is the id of the HTML div used for the buttons, e.g. 'pedigree_history'.
dataset
The pedigree data to be displayed, e.g.
[ {"name": "m21", "sex": "M", "top_level": true},
  {"name": "f21", "sex": "F", "top_level": true},
  {"name": "ch1", "sex": "F", "mother": "f21", "father": "m21", "breast_cancer":  true, "proband": true}]
labels
Array of attributes to display under the individual's symbol, e.g. labels: ['age', 'yob', 'alleles'].
font_size
Define the font-size of the labels, e.g. '0.75em' or '10px'.
font_family
Define the font-family of the labels, e.g. 'times'.
font_weight
Define the font-weight of the labels, e.g. 400, 700.
width
Width of the SVG element, e.g. 600.
height
Height of the SVG element, e.g. 400.
symbol_size
Size of the nodes, e.g. 35.
store_type
Pedigree storage (for undo, redo functions) set to 'session', 'local' or 'array'. Default is 'session' browser storage. Using 'session' will store the data for one session (data is lost when the browser tab is closed). Using 'local' will store the data with no expiration date. If session/local storage is not supported then it switches automatically to 'array' (JavaScript array store).
zoomIn
The factor by which the svg size can be scaled down to, default 1 (no zoom in).
zoomOut
The factor by which the svg size can be scaled up to, default 1 (no zoom out).
zoomSrc
The source of zoom events, default ['wheel', 'button'] (zoom with mouse wheel and zoom buttons).
edit
Set to true for a button to display an individual's details (e.g. age, sex) in a dialog or provide a funtion to handle editing.
diseases
Diseases and their colour representation, e.g.
[{'type': 'breast_cancer', 'colour': '#F68F35'},
 {'type': 'breast_cancer2', 'colour': 'pink'},
 {'type': 'ovarian_cancer', 'colour': '#4DAA4D'},
 {'type': 'pancreatic_cancer', 'colour': '#4289BA'},
 {'type': 'prostate_cancer', 'colour': '#D5494A'}]
background
SVG background colour, e.g. #d3d3d3.
node_background
Individual's background colour, e.g. #fff.
validate
Pedigree data validation (default true). This can also take a validation function to override the in-built validation. The in-built validation throws an error if any of the following are not true:
  • parents, when defined, exist in the pedigree
  • mother is female
  • father is male
A warning message it sent to the console if there are any individuals that are not connected (i.e. a break in the pedigree). See the developer notes for more details.
DEBUG
Debug mode, e.g. false.

Publication

pedigreejs: a web-based graphical pedigree editor
Carver T, Cunningham AP, Babb de Villiers C, Lee A, Hartley S, Tischkowitz M, et al. Bioinformatics doi:10.1093/bioinformatics/btx705