Student Name:  	 Stephen Federowicz
Mentor Name: 	Scooter Morris
Title: 	CyAnimator: A general purpose animation tool for Cytoscape
Abstract: 	A tool that cycles through and animates a user specified list of features would help to visually differentiate datasets, pathways, and attributes from and within large biological networks. These features would be sets of nodes and edges that would be generated based upon the network topology and data attributes. They would then be made available for the user to specify which features to animate within the network along with what visual attributes should be assigned to each feature. 

Overview

User Guide

The CyAnimator has seven buttons and one slider. The add frame button captures the view of the current network and stores
it as a key frame in the animation. It also adds a thumbnail to the thumbnail viewer for easy handling and viewing of the
key frames. Once you have a thumbnail or multiple thumbnails you can right click on them to enable a popup menu which will
allow you to move that frame, delete that frame, or set the level of interpolation between that frame and the next. A left
click will restore the view of that key frame as the current view on your Cytoscape desktop.

The other six buttons should be familiar, they are the play, pause, stop, pause, fast forward, and backward(in this case step
forward and backward) and record. They all work just like on a VCR or DVD player except for record which simply outputs the entire
animation as a set of image files. If you are using the prototype version the images are by default outputted to your-current-cytoscape-directory/outputImgs
from here you can compress them into a movie. Also note that when you hit the record button it will take about 2-3 minutes to output
all of the images given the length of the animation.

Finally the slider adjusts the speed of the animation, by default it is set to 30 frames per second and goes down to 1fps and up to 60fps.

At this point that is all you should need to know so have fun. In the future support will be added to turn on or off different types
of interpolation on the fly (i.e. if you want to interpolate color but not the position). There will also be interpolation support
for many more types of visual attributes.

Check out an example movie here  http://www.youtube.com/watch?v=LmtIlyPApZI, and download the latest jar file below. Note that if you simply
download the jar file into your-current-cytoscape-directory/plugins/core, it will immediately appear in the plugin drop down menu.

Project

Use Cases

1. Animate pathways or pieces of pathways within a larger network (i.e. animate subnetworks).

Example:

Bring up a large protein-protein interaction network or merged set of a number of different known pathways.
Within this large network there are a number of either full pathways or gene sets, or at least pieces of pathways
and gene sets which are subnetworks of the larger network. In my case I had a merged network of a number of different
pathways involved in different cancers, I then had a separate list of perturbation and enrichment values for gene sets
and pathways generated from a separate statistical analysis of genome wide array CGH data from tumor biopsy
samples. Given that the pathways and sets I had overlapped with the ones in the network, I want to view what pathways
are most affected across patients and in different subtypes to see if I can glean some insight into what pieces of the
molecular machinery are broken or missing.

2. Animate across multiple gene expression, CGH, or RNAseq data sets on top of a network.

Example:

You have expression data from tumor biopsies of patients with breast cancer which is known to exist in multiple distinct
molecular subtypes. After classifying the data into these subtypes you can set up an animation which cycles through the
expression profiles for each subtype to see what pieces of the network differ between the distinct classes. This can
already be done with the Dynamic Expression plugin except here we might also animate other visual properties.

Example:

You have expression data from multiple different species and you want to see what the cross species difference is on a pathway
or molecular network that is shared between all of the species. An especially interesting case would be between species who are
known or thought to have evolved along the same lineage.

3. Animate individual pathways, or networks with directed edges to flesh out the interaction details of complicated pathways.

Example:

Looking at something like  http://www.wikipathways.org/index.php/Pathway:WP274 , we see that an intense amount of detail is inherent
in many pathways. The goal here would be to allow a user to click on a single protein etc.. in the pathway or network and then for
an animation to occur which would be a diffusion out along the directed edges, such that a sense of the pathway architecture can be
visually inferred. I imagine the animation to be much much like waves in a pond after you drop a rock in the middle. I see this as
being potentially very useful as a learning tool for someone who is not a specialist in a certain field but for whatever reason finds
themselves needing to make sense of a complicated pathway.

Timeline

Week 1

Analyze use cases and determine the scope of functionality that will be provided. Discuss what the proposed functionality will mean
in terms of technical requirements and begin to jump in to the actual design.

Week 2-6

Change course and adopt a key frame approach as it will ultimately allow for any type of data visualization to be built on top of it.
Start by realizing that a CyFrame class will need to be created to essentially encapsulate a CyNetworkView because network views
can not really be instantiated. Build this class along with an Interpolator that automatically interpolates node color and position
between any two frames (will soon support more visual attributes). Finally build a GUI that displays thumbnails of the different
frames in the animation to provide an intuitive interface for creation.

Week 7

-Animations can exist as a collection of attributes such that each element in the collection is a frame in the animation.

-Animations can exist as a collection of views, however currently this must be accommodated with an encapsulating CyFrame class.

Design Description

Overview

The design brakes down into three main classes; CyFrame.java, FrameManager.java, and Interpolator.java. CyAnimatorDialog.java is
also important and contains all of the swing GUI code but is fairly self explanatory and deliberately made separate from
the other code so an not to introduce any swing dependencies. The result is that CyAnimator can be used in "headless" mode
by other Cytoscape plugins who wish to use the animation facility but do not need the GUI. Overall the CyAnimator was designed
to provide a key frame animation facility for Cytoscape. It does this by simply capturing view data from a networkView and then
doing the appropriate interpolation and updating of the network view to create an animation. The primary goal is to help
contextualize very large and seemingly disparate data sets.

CyFrame

The CyFrame class is essentially a wrapper on a CyNetworkView. It works by having a populate() method which essentially extracts the
necessary view data from the current CyNetworkView and stores it in the CyFrame. Each CyFrame also contains a display() method which
updates the current network view based upon the visual data stored in that particular CyFrame. It also can hold an image of the network
and contains a facility for writing this image to a file.

FrameManager

FrameManager is the driving class for the animations which holds the list of key frames, creates and manages the timer, and essentially
makes the animation. The primary function is to create a timer ( http://java.sun.com/j2se/1.4.2/docs/api/java/util/Timer.html) which
fires an action command at a specified interval displaying each frame in the animation in rapid succession. There is also support
for all of the standard, play, stop, pause, step forwards, step backwards commands along with code to set up the exporting of images.

Interpolator

The Interpolator is what make the animations go smoothly. It works by taking a list of the key frames for the animation from which it
determines how many frames will be in the final animation after interpolation. It then creates an array of CyFrames which gets "filled"
with all of the interpolation data as it is generated. This works by creating lists of FrameInterpolators which is a generic interface
(FrameInterpolator.java) that has only one method, interpolate(). There are then many inner classes in Interpolator.java which implement
FrameInterpolator and do the interpolation of a single visual property. For example there is currently interpolateNodeColor, interpolateNodeOpacity
interpolateNodePosition, interpolateEdgeColor, interpolateNetworkColor etc... Thus the design is such that many interpolators can ultimately
be made and swapped in or out at will. After the set of interpolators are decided, they are iterated through and all of the NodeView, EdgeView,
and NetworkView data is interpolated appropriately for each frame in the frame array.

Implementation Plan

1. Discuss use cases and determine scope of functionality.

2. Determine how attributes will be automatically grouped or filtered to meet the demands of the proposed animations.

-Write the code for this so that the GUI building will have features ready to work with.

3. Figure out what type of user interface will be necessary to facilitate the animation and build it.

4. Write the code for the animations(potentially simultaneously with step 3).