Mini-Retreat One

• September 12-13, 2008

• "Department of Bioengineering" (Powell-Focht Bioengineering Hall), UC San Diego, Room 291

• Mike's cell: 858-228-7242
• Mike's office: 858-822-4756

Topics for Discussion

• Progress on merging the new CyNetwork and CyAttributes model with the 3.0 branch.

  • CyAttributes API changes based on retreat discussions (Trey's references notes), CyDataTable

• Discussion of how Groups will fit in to the model package.

• Discussion of how HyperEdges will be handled.

• Progress on ViewModel API?

• Division of Labor - figure out what tasks can be separated out amongst other groups.

Meeting Notes

pre-meeting comments

• Gary opinion, Sep8 - Re: groups. Groups definitely belong in the model, but they should be kept separate from the core network model. There should be a CyGroups API similar to the one that exists that keeps track of all group information. Algorithms that work on simple graphs (most of the existing Cytoscape and plugin code) will not need to know about groups and those that need groups will be able to access the information using the CyGroups API. Group views on the other hand will likely need a lot of custom node shape functionality in the view layer. This is how Hyperedges should work as well.

• Piet opinion, Sep9 - Re: goal. Isn't division of coding-labour one of the goals of these mini-retreats also?
• Scooter, Sep 11 - I'm starting to get concerned that people might be spending too much time moving plugins over the Cy3 trunk without knowing how much the API is still in flux. We still haven't even talked about the View API much and a lot of plugins leverage various view features extensively. I think we should talk about exactly how people should be viewing Cy3 at this stage. We're going to have a lot of people really upset with us if they do a lot of work that has to be completely redone. On the other hand, we want people to give us input about what's missing in the tree, so some work is warranted.

Goal

Goal is to discuss these core layers and target an API for this core to allow more rapid, distributed porting and development

Minimal set of core layers to focus on:

• Data (CyAttributes, CyDataTable)

• Network 

• ViewModel

• PresentationView (Renderer)

• Command (Tasks, Tunables)
• I/O
• Event Handling

CyDataTable

public interface CyDataTable {

        /**
         * A public CyDataTable is a table that is accessible to the user
         * through the user interface.  Private or non-public CyDataTables will
         * not be visible to the user from the normal user interface, although
         * they will be accessible to plugin writers through the API.
         * @return Whether or not this CyDataTable should be publicly accessible.
         */
        public boolean isPublic();

        /**
         * @return The session unique identifier.
         */
        public long getSUID();

        /**
         * @return A human readable name for the CyDataTable.
         */
        public String getTitle();

        /**
         * @param title The human readable title for the CyDataTable
         * suitable for use in a user interface.
         */
        public void setTitle(String title);

        /**
         * The keySet of this map defines all columns in the CyDataTable and the
         * the values of this map define the types of the columns.
         * @return A map of column names to the {@link Class} objects that defines
         * the column type.
         */
        public Map<String,Class<?>> getColumnTypeMap();


        /**
         * @param columnName The name identifying the attribute.
         */
        public void deleteColumn(String columnName);

        /**
         * @param columnName The name identifying the column.
         * @param type The type associated with the column. 
         * @param unique Whether the entries in the column are unique. 
         */
        public <T> void createColumn(String columnName, Class<? extends T> type, boolean unique); 

        /**
         * Unique columns can be used to map the values from one CyDataTable to another.
         * @return A list of column names where the values within the column are
         * guaranteed to be unique. 
         */
        public List<String> getUniqueColumns();

        /**
         * @param columnName The name identifying the column to return.
         * @param type The type of the column to return.
         * @return The list of values of type T that exist in the column specified by
         * the columnName.
         */
        public <T> List<? extends T> getColumnValues(String columnName, Class<? extends T> type);

        /**
         * @param primaryKey The primary key index of the row to return.
         * @return The {@link CyRow} identified by the specified index.
         */
        public CyRow getRow(long primaryKey);

        /**
         * @return A new {@link CyRow} object for this CyDataTable. 
         */
        public CyRow addRow();

        /**
         * By default all {@link CyRow}s created have a primary key column of
         * type {@link Integer} that gets created at initialization which is
         * identified by this string.
         * If the CyDataTable is created and immediately bound to a {@link CyNetwork}
         * then the primary key attribute is populated with the SUID of the 
         * {@link GraphObject}.
         */
        public static final String PRIMARY_KEY = "AID";
}

• CyDataTable presents a worksheet abstraction to plugin writers. There will be multiple CyDataTables, some of which are bound to a network, and some are not.

• Bound CyDataTables are created with the node SUID as the primary key, in unbound CyDataTables, the primary key is an auto-incremented long

• The addRow method in CyDataTable does not take an argument, however, for efficiency purposes, the CyDataTable implementation will have a protected method, addRow(long SUID) that will be used by GraphObjects

• CyAttributes replaced by CyRow

• CyFunction - beginnings of formula support, will initially be used for references

CyDataTable Data Types and Serialization Proposal

• CyDataTable will support nested Lists and Maps.

• The data contained in a List or Map will be serialized to XGMML as a simple string. The string will then be parsed by CyDataTable and converted into the proper data type.

• COMPLEX attributes will not be supported in their current form. However, because nested lists and maps are supported, you'll be able to accomplish everything that COMPLEX types can.

• MultiHashMaps, MultiHashMapDefinitions, and COMPLEX_TYPE in particular, will go away.

CyMetaNode

Tackled CyGroups: Selection/Filters/NamedSelection(Groups)

• should selection be an attribute?
• selection model in cytoscape 3.0 could be tied to vizmapper, allowing flexible visual indication of selection (inspired by Gang Su's UI work with GLay)

• How CyGroups works...

• Should we go all the way and shoot for a Compound Graph?

• Approach: we extend CyNode and CyNetwork to CyMetaNode and CySubNetwork.

  • CyMetaNode adds one additional method:

    • getChildNetworks(): which returns the CySubNetwork that this network is part of.

  • CySubNetwork adds three additional methods:

    • getParentNode: returns the CyMetaNode that contains (or represents) this sub network.

    • copyToNetwork(CyNode node): copies the node "node" into this subnetwork (adding it to the metanode)

    • removeFromNetwork(CyNode node): removes the node "node" from this subnetwork

• This leaves us with a problem -- currently, there is no way for a Network to have a "hidden" node. We do this currently because we have the root graph, which was one of its nice "features". If we add a CyRootNetwork, then we can get the benefits of the root graph for this network and its children only. For most plugin writers, they will never see this:

  • The CyRootNetwork is just a CyNetwork with four new methods:

    • getAllNodes, returns the list of all nodes in the network, including any CyMetaNodes

    • getAllEdges, returns the list of all edges in the network, including any meta-edges

    • createMetaNode, creates a CyMetaNode with a list of Nodes

    • removeMetaNode, removes a CyMetaNode from the CyRootNetwork and its associated CySubNetwork, but does not remove the contained nodes

    • getAllSubNetworks, returns all of the CySubNetworks that are managed by this one CyRootNetwork

• Need a CyRootNetwork and CyNetwork

  • a CyNode can contain a CyNetwork

• the CyRootNetwork contains nodes, obviously, but cannot be contained itself

• default behaviour getCurrentNetwork.getNodes() returns the nodes currently viewed based on the state of the collection of CyNetworks

• advanced usage allows you to ask if current CyNetwork is the root, if yes, then type it as such, then call getAllNodes()

• Discussion: When do we extend CyNetwork vs. use well-known attributes? In the case of compound networks (metaNodes) we decided that they required additional semantics, so CyNetwork was extended. In the case of HyperGraphs, we're going to use nodes in any case, so we are not going to change the semantics. Therefore, a connector node will be identified by the NODE_TYPE_ATTR attribute.

  • subclassing and extending an interface follows from the intention to change the semantics. If the semantics of a class are changed by new methods, then you should extend/subclass; if the semantics are unchanged, the same class should be used.

• CyDataTables will getSUID and get/setTitle. There are specific semantics in Network. When a data table is bound to a network the title is then mapped to a namespace (per network): SUID and namespace are fixed, title is not.

HyperEdge

• NodeType attribute namespace to handle connector nodes (not another subclassing of the interface)

• Continue to use the concept connector node, the strategy of the hyperedge plugin, rather than go after a formal hypergraph

ViewModel / Presentation Requirements

• Extensibility is key.

• What is the granularity of extensibility? Should it be Node and Edges (i.e. NodeRenderer, EdgeRender), Network (just one renderer for the whole shebang), or VisualProperty (one renderer per visual property)?

• Where are VisualProperties defined? Are they a function of a renderer or are they intrinsic to the ViewModel. Should there be a third class (e.g. VisualPropertyProvider)?

  • Who handles serialization and de-serialization?

  • Should there be default or "essential" set of VisualProperties?

  • How doe VisualProperties meaningful in one context (e.g. Paint in java) get translated into a different context where the concept isn't meaningful (e.g. there is no Paint in SVG)?

  • Does VisualPropertyProvider (assuming such a thing exists) have a user interface? How does the VizMapper provide a UI for a VisualProperty that it has never seen before? Presumably the VisualProperty will have some definition of the variable or variables that describe its range of flexibility. Is there a mechanism for the VisualPropertyProvider to provide handlers for setting unknown properties in the VizMapper. Can you provide new VizMapper editors?

• ViewModel must not depend on the Renderer. Cytoscape's data layers should be usable without a Renderer. Imagine a webservice.

• How to handle multiple layers of a presentation? Background/foreground images?

• VisualProperty needs to be able to describe how attributes (attribute types and editor types) can be mapped to this VisualProperty.

Plans and Decisions

• Work on unit tests against the interfaces