caleydo / lineage

Tree-based graph visualization: genealogies and general graphs 💬 @cnobre

Caleydo - Visualization for Molecular Biology

Caleydo is a visualization framework for molecular biology data. It is targeted at analyzing multiple heterogeneous but related tabular datasets (e.g., mRNA expression, copy number status and clinical variables), stratifications or clusters in these datasets and their relationships to biological pathways.

For user documentation please refer to the Caleydo Help. For general information and downloads based on binaries please use the Caleydo Website. This guide assumes that you want to install Caleydo from source.

Installation

Caleydo uses Java, OpenGL and the Eclipse Rich Client Platform (RCP). Things you need to install before being able to run Caleydo:

• Eclipse Kepler for RCP and RAP Developers, which you can get from the eclipse download page. Other Eclipse versions won't work.
• Install EGit in Eclipse using software updates.
• Java SDK >= 1.7

To install Caleydo use EGit within Eclipse and clone the repository. Each directory in the caleydo-dev folder corresponds to an Eclipse project. Here is a good tutorial on how to import Eclipse projects from git.

If you want to use ssh (instead of https) for communicating with github out of eclipse follow these instructions. You will have to generate a new RSA key and save it to you ~/.ssh folder. Remeber to set a passphrase for you key. This will result in a file ida_rsa and ida_rsa.pub turning up in your ssh folder. Save your public rsa key with your eclipse account folder.

When cloning the repository follow the above tutorial. Don't change the username "git" to your username!

Team

Caleydo is an academic project currently developed by members of

• Institute for Computer Graphics and Vision at Graz University of Technology, Austria
• Institute of Computer Graphics at Johannes Kepler University Linz, Austria
• Pfister Lab at the School of Engineering and Applied Sciences, Harvard University, Cambridge, USA
• Park Lab at Harvard Medical School, Boston, USA

Acknowledgements

Caleydo makes use of a range of open source tools, bioinformatics resources and pre-packages several datasets, which we gratefully acknowledge here.

Software Libraries

• Bubble Sets - A Java implementation of the visualization technique.
• CDK - The Chemistry Development Kit.
• JGrahT - A graph library.
• Jogl - Java bindings for OpenGL.
• PathVisio - loading and parsing WikiPathways.
• WordHoard - statistical utilities.

Bioinformatics Resources

• David Bioinformatics Resources - Gene ID mapping.
• KEGG - Pathways.
• WikiPathways - Pathways.

Datasets

• CCLE - BROAD Institute Cancer Cell Line Encyclopedia.
• TCGA - The Cancer Genome Atlas.

Resources

• GitHub - Hosting our source code.
• WebStorm - Free developer licenses for our web projects from JetBrains.

lineage's Issues

Improve lifeline by showing life or death

Show lifelines also for people still alive, but use a stippling at the end to indicate that they're still alive.

Terminate lifelines of dead people:

Center text in labels

Not quite in center vertically.

Left-over artifacts when scrolling out

See:

Nodes dissappear when I click on them

See:

Visualize flexibly mapped primary attribute in graph.

As discussed in #17, we want to be able to select a primary and a secondary attribute for direct mapping in the graph.

The primary mapping will determine the node color. For categorical values, we will choose a qualitative color scale (black/white for binary categories, this colorbrewer scale for multiple categories) and visualize a legend of the color scale at the bottom of the graph.

For continuous color values, we will use a quantitative color brewer scale, appropriately treating quantitative continuous and diverging scales. Again, we will visualize a legend at the bottom of the graph.

Two components:

• One-node mapping works.
• Legends implemented.

Add axis to numerical table columns

For numerical values, add a permanently visible axis, like this one (but on top):

Edges are drawn on top of nodes when genealogy is redrawn

• Release number or git hash: b2cc6ce
• Web browser version and OS: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36
• Environment (local or deployed): local (npm start)

Steps to reproduce

1. Scroll the genealogy all the way to the bottom
2. Start scrolling back up to force re-rendering of the genealogy.

Observed behavior

• Edges are drawn on top of nodes.

Expected behavior

• Edges are drawn behind nodes.

missing life line (or extremely short life line?)

• Release number or git hash: b2cc6ce
• Web browser version and OS: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36
• Environment (local or deployed): local (npm start)

Steps to reproduce

1. Launch app.
2. Scroll genealogy down to nodes with id "17"

Observed behavior

• One individual doesn't seem to have life line.

Expected behavior

• A life line or other indicator why the individual doesn't have one.

when hidding nodes: how to deal with branches that end with no affected children.

This doesn't happen in our current suicide dataset but if you change the 'selected' attribute, that can (and will) happen.

Have to think about how to handle this.

Make lables in nodes definable

I don't think the current implementation with age is necessarily always helpful.

We could think about what we can put in there - maybe something related to primary (#18) or secondary (#19) attribute.

change aggregation behavior on click and drag to show stippled node @ original location and only aggregate on release

Right now, clicking and dragging on nodes moves their position and the associated edges. Instead, leave the edges in place, create a 'phantom' stippled node in it's place and only aggregate when the user releases the mouse.

Preserve selected rows on scroll.

Observed behavior

*In order to preserve selected rows on scroll, clicking on a row modifies the data bound to the element to 'selected' = true. The problem with this is that when the user clicks on a new row (not in multi-selection mode/cmd key) that doesn't modify the data of the previously selected row(s).

Expected behavior

• When user clicks on a row without cmd, it should clear all other selected rows (including the ones outside of the viewport)

Track state and history of state

We want to be able to track all major actions in the URL, and ideally also as a history that supports undo/redo. Even if we don't do it using clue, there are different approaches. Sunny did that well in VIDER, which you can find here:

https://github.com/visdesignlab/survey-vis

I'll ask him about details.

Line-selection of nodes can only apply to the right-most node

When hiding nodes, the respective lines of the hidden elements are also selected:

I would suggest that for rows where nodes are aggregated, only the area righ-most of the node is selected.

Alternatively, any area that is not directly on a node selects the right-most node, but you'd have to try whether that's intuitive.

Hidden nodes should be highlightable, but not using the line highlight, but by highlighting a frame.

Table: Visualize Categorical data in matrix (no color)

Let's visualize categorical data like this:

I.e., when we have categories of one class, we still show a whole column for each category (e.g., male and female get their own column). Between categories of different classes, we increase the spacing (as in between female and suicide).

age in node and age on "life line" doesn't always match

• Release number or git hash: 8686bbb

Steps to reproduce

1. launch the software

Observed behavior

• age in node and age on "life line" is off by 1 for some individuals
  

Expected behavior

• both displayed ages are the same

Add settings panel and add settings

Add a panel that can be dynamically hidden for displaying settings.

Add settings:

• show/hide lifeline
• scale column height/node size

I'm sure we'll think of more as we work on this.

Table: Allow for 'super categories' (for ICD9 code for example) that can then be expanded to sub categories

Table headers should remain visible at all times

See:

The headers should always be visible, as they are in the tree. The tree implementation might be a little more complicated then necessary for this. A separate SVG might be the simplest solution?

Have Table and Attribute Panel access and modify the same table data structure.

Events will still be used to notify when something in the table has changed (such as the order of the attributes, or which ones are tagged as 'selected') so that the table / panel can update its view accordingly.

Properly handle parent-parent edges for people with multiple partners (not @ the same time)

Observed behavior

• Missing parent-parent edge for one of the father/mother combinations

Expected behavior

• All couples have a parent-parent edge.

Select category or feature range to drive the primary attribute

As the primary attribute determines the layout of the graph, we need to be able to define what is "in" and what is "out".

For Categorical data, we want to select 1-n categories to make up the primary attribute.

For Numerical data, we want to be able to brush a region.

Enable switching between families.

Like in UpSet, we should be able to switch between different datasets through the user interface.

While we will hopefully have a couple of interesting pedigrees, it's also useful to load dedicated test-datasets.

Use SASS for css color definitions

Use sass to define colors with variables: e.g: $nodeColor : 'black'

Allow user to select primary and secondary attributes through the attributes panel

The primary attribute is moved to a special spot at the top. The secondary attribute is moved to to a special spot right below it.

In a first iteration, we just pick one category to be the primary.

Allow users to define baseline year for age calculations

For some users, it might be important to be able to fix the date (e.g. if they are working on a data set that should not be changing (e.g. for screenshots or analyses), while other users will be ok with seeing the age relative to the current year.

We should allow users to view age relative to the current year (i.e. use https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getFullYear) or to provide a baseline year.

At a minimum, we should define a global variable for the baseline year.

Synchronized highlighting between graph nodes, table rows

When I move the mouse over a node, it should highlight, a line connecting it to the table row should appear, and the table row should be highlighted (with a frame).

We need two different highlight modes:

• click
  • use #ff6400 for frames
  • use same color with alpha 0.2 for background / connection lines
• mouse over
  • use #ffc800
  • use same color with alpha 0.2 for background / connection lines

Resize Table Columns by Dragging

Should be able to dynamically resize the column widths, ie by clicking and dragging.

Two possible behaviors:

1. This shrinks all the other column widths ("widening the column")
2. This shrinks the column widths of the neighbor on the side that's being dragged ("moving the boundary")

Option 2 is the behavior in, ie Google Sheets, so that might make more sense and is easier to implement...

• Would also be nice to have a reset mechanism- ie, double clicking the column.
• Might be good to have a minimum column size (say N pixels), so that you cannot squash columns down smaller than N pixels. (If you want a column smaller than N pixels you should probably delete it)

Add header to table columns

We need to be able to tell which attribute is in which column. I'd suggest to use 45degree angles, as in this example:

Maybe to the other side though.

Make data-selection panel resizable

While this isn't a big deal in general, it uses a ton of space right now.

Have graph interact with table data structure for all attribute information.

When changes are made in the attribute panel, the table data structure will be modified by the panel view and an event fired. The graph should listen to these events and update the layout of the graph and which nodes are "affected" accordingly.

Differentiate between click/click and drag, differentiate between click/double click

currently the click and drag behavior is disabled. Double click (which is used to expand aggregated nodes) still triggers click twice (which is fine for now since all click does is toggle the 'selected' state of a row)

Visualize flexibly mapped Secondary attribute in graph.

For the secondary attribute, as introduced in #17, we will use the space to the right of the node.

Here we distinguish quantitative and categorical values. We will also allow to visualize multiple values taken at different times in peoples lives. A special case is a person's age, which will be visualized as a the already implemented life-line.

The figure shows the three cases:

• first, events associated with specific time point in a person's life.
• second, a quantitative value, shown in a small, framed bar chart
• third, a categorical value, shown in a slim colored rectangle right of the node. In case the primary attribute encodes a multi-class category, this will be replaced with a shape.

On mouse-over, the detailed values are shown in a tool tip.

For the categorical case a legend will be shown below the graph (either showing symbols or colors).

When User changes primary attribute, have graph uncollapse, animate the change in which nodes are 'affected' , and recollapse.

Aggregation Rules

If there is a primary attribute present in a given generation, all non-affected members of this generation are aggregated, but the generation is preserved through the affected individual node and the aggregate node for all non-affected.

If there is no primary attribute present in a generation, it gets rolled up in to an aggregate in an older generation up to the level where the aggregation was triggered from.

Give data selection panel a static initial size

Right now, the data selection panel uses the column layout. However, on a large screen that doesn't look good:

The data selection panel is probably better off with a static (initial) width in pixels.

Allow to select primary mapping attributes in data selection panel

From the list of attributes, we want to be able to select

• one primary attribute that drives the coloring of the nodes. In our common example this is "committed suicide"
• one secondary attribute that is displayed to the right of the node. Currently, this is the "life line", i.e., the life span of the people.

Both can be either categorical or numerical or an item measured multiple times over a person's life.

These could be realized using a dedicated button associated with each entry:

When an item is selected to be the primary or the secondary attribute, the button will be highlighted and will always be visible. Otherwise, these buttons are only visible on hover (this isn't correctly shown in the sketch).

Gender is explicitly excluded, since this is encoded in the shape.

Allow to select item from data selection panel and add it to table

We need to be able to select features to show in the table.

Add context menu for each node (options to aggregate all descendants or hide attribute row in table)

Use an initial gear symbol, like in pahtfinder:

In the menu, distinguish between

• Hide all children
• Hide all children unaffected by $primary_mapping_variable

Sort table based on an attribute

We want to be able to sort the table based on any attribute by interacting with the table header.

On sort, we'll add a slope chart between the tree and the table:

Enable aggregation of nodes in table

The table should accurately display an aggregation set by the graph.

In a first iteration, we will use the following visual encodings for quantitative and categorical data:

• Dot plots with jitter in y direction to encode all the elements in the aggregation, a vertical line at the median value. On hover over a dot we want to display the exact value of the entry and highlight the corresponding person in all other columns.
• In line with the categorical vis introduced in #10, aggregated categories will be displayed as a bar chart that is filled horizontally, proportional to the number of people that are in this category. On hover, a tool tip will show the number of the persons in that category and will highlight the people in all other columns of the table.

Replace Graph with a matrix visualizing the kinship coefficient

Especially in cases where we have people that are not in the pedigree (see #23) we want to show the kinship coefficient, i.e., a score of relatedness between all people.

We will realize this as a matrix. The matrix should support various seriation options, also by table sorting (see #24). Potentially use reorder.js for that.

Add ability to hide all people/nodes not related by blood to the founder (i.e spouses)

Hide years when there is not enough space

What we probably want to see is the first and the last year in this aggregated space.

Allow to hide data selection panel

Add a button in the header that hides the data selection panel.

Here is an example on how this should work:

http://pathfinder.caleydoapp.org/main.html#

Kids are placed in the wrong y position in multi-spouse families.

Observed behavior

• The affected male kid in this example is the child of the mom with the affected dad. So he should be placed next to the other two male siblings (lower y than the unaffected dad)

Integrate people that are not in the Family

We want to add people based on shared attributes. Not sure about the details yet.

Properly align table with graph

Right now, the table isn't correctly aligned with the graph:

Duplicate Node when someone had children with more than one partner.

This will make the layout cleaner and avoid a long vertical line connecting that person with two partners.

Keep in mind this will mean personIDs are no longer unique and cannot be used as keys for nodes/table rows. May have to start passing the person's "y value' as well when sending events to the table.

Order of children off in multi-people relationships

The offspring of one couple should always be next to each other, even if one of the couple has children with other people. Here is a broken example:

The second node from the top should move down one row.