## These are wiki comments - leave them in so that people can see them when editing the page

## This template may be useful for documenting use cases 
## Developed in response to a hackathon request for formalized, detailed use cases 
##  to help direct implementation proposals

|| '''Use Case Name''' : Protein Complexes ||
|| '''For Feature''' : Groups ||
|| '''Editors''': Alex Pico ||

## EXAMPLE: 
## Use Case Name: Representation of Protein Complex
## For Feature: Grouping Function
## Editors: Mr. Knowitall

<<TableOfContents([2])>>

== Summary ==
## Provide a one paragraph description of the use case

We would like to be able to represent two or more proteins as macromolecular complexes in pathways. The representation of complexes will help simplify the visualization of complicated biological systems.  Furthermore, complexes themselves have properties and interactions that we'd like to support and store.

== Step-by-Step User Action ==
## Provide a step-by-step account of how the user would execute the use case.  For example: (1) right click on node, (2) choose "expand" from context menu, (3) new view is created, etc...

'''Creating a New Complex'''
 1. Select two or more nodes
 1. Choose "Form complex" from a context menu, main menu or toolbar
 1. Automatically view collapsed view of complex with default label (editable)
 1. Be able to expand complex as vertically stacked set of nodes by a very simple mechanism (e.g., click on a plus/minus icon)
  a. perhaps other restricted views of the children will be allowed:
   i. horizontal stack
   i. block (e.g., 2x2, 3x4)
   i. overlapping "clump" of nodes packed into a some defined circular area
   i. new network
 1. Be able to destroy complex
 1. Be able to expand-all or collapse-all complexes in a given network

'''Loading a Network with a Complex'''
 1. Same as 3-6 above

== Visual Aides ==
## Provide attachments to images to illustrate the use case (screenshots, mock-ups, storyboards, etc)

{{attachment:Wnt_GenMAPP.jpg}}

In this GenMAPP pathway, stacked gene objects help indicate complex and paralog groups.  For example, Rhoa + Racgap1 and Gsk3b + Apc

== Requirements for Cytoscape ==
## List the components/functions already in Cytoscape that are relevant to the use case and possible implementations (e.g., "current context menus can be used accomplish step 2 above")
## Also list components/functions that are needed in Cytoscape to execute the use case (e.g., "cytoscape needs to allow for multiple views of the same network for this to work")

 * The Group API can handle this one in terms of create, expand, collapse and destroy
 * Need to implement a simple GUI that is specific for complexes, i.e., uses semantics relating to protein complexes
 * Need to add simple layout/alignment algorithms for stacking children vertically in expanded view
 * Need to support the storage of complexes in a pathway file format. xGMML and GenMAPP's GPML?

== Importance ==
## Describe whether this use case is critical and how frequently users would come across it.  Describe common work flows that might involve the use case (e.g., "this use case comes up regularly, on a weekly basis, whenever we want to analyze our protein superfamily networks").

This is a very important use case, critical to almost ''every'' pathway.  The typical user would expect quick, intuitive control over this feature, mainly for simplifying (or digging deeper into) a given pathway representation.

== Other Examples ==
## List other applications or relevant examples outside of Cytoscape that provide some or all of the desired functionality (e.g., "You can do this using the group function in PowerPoint").

 * Simple, intuitive examples of expand and collapse can be found in directory tools/explorers that let you click on an icon (e.g., a triangle or plus/minus) to expand and collaspe the view.
 * Illustrator and other such programs have a grouping function that mimics the restriction on children once a group is formed.  You cannot move the children relative to eachother, for example.  If you want to treat them independently, you have to ungroup.

== Comments ==

AllanKuchinsky - 2006-11-27 07:16:15
 
This suggests a sub-project to define a set of "visual formalisms" for the view aspect of Groups.  Visual formalisms are "diagrammatic notations with well-defined semantics for expressing relations.  They ae based on simple visual notations such as tables, graphs, plots, panels, and maps.  Versions of such visual notations that define a precise semantics become truly formal".   This is described in Nardi and Zarmer, 1990, which is attached [[attachment:nardiZarmer.pdf]] 


AllanKuchinsky - 2006-11-27 07:33:55
 
The idea would be to build a small set of visual formalisms, e.g. vertical/horizontal stacks, tables, that could be readily specialized to views for complexes, paralogs, protein domains, etc.