Purpose

The purpose of this document is to provide a brief overview of the Cytoscape 3.0 API. This will not give an in-depth look at any particular part of the system, but rather to understand where to look for things you might need.

Networks and Attributes

API Jar: model-api

Namespace: org.cytoscape.model

Your network is represented by a CyNetwork and attributes about your networks are stored in CyTables. CyNetworks are composed of CyNodes and CyEdges and have the usual methods you’d expect (get neighbors of a node, get all edges, etc..). Likewise CyTables contain CyColumns and CyRows. Tables are allowed to contain values of type integer, long, double, string, boolean, and lists of integers, longs, doubles, strings, and booleans. Each table has a primary key column which can be of any type, but the values within the column must be unique. Accessing values from a table uses a single method with a type argument, rather than different methods for each type. This means you call row.get(“isSet”,Boolean.class) rather than something like row.getBoolean(“isSet”).

Each CyNetwork has by default three CyTables automatically bound to it, one for nodes, one for edges, and one for the network itself. The primary key in each case is the SUID associated with each object. Rows in these default tables are accessed through the CyNetwork.getCyRow(obj) where obj is the node, edge, or network whose row you're looking for. So, to get the name of a node, your code would look like: network.getCyRow(node).get(“name”,String.class).

Events

API Jar: event-api

Namespace: org.cytoscape.event

The event package is how Cytoscape communicates its state changes with third party objects. One notable difference in Cytoscape’s event handling model is that all events are fired through and all listeners are managed by the CyEventHelper. To register as a CyListener for a CyEvent, you simply need to register your CyListener as an OSGi service.

Visualization (View) Model

API Jar: viewmodel-api

Namespace: org.cytoscape.view.model

Visualizing things in Cytoscape means that we create a View of the object. The View interface is parameterized, so a view of a CyNode is View<CyNode>. A view for a CyNetwork is a CyNetworkView which extends View<CyNetwork> by adding a few additional methods. The View interface primarily serves as a container for VisualProperty objects.

The VisualProperty interface is an abstract definition of some aspect of an object that can be visualized. So given a node, some VisualProperties associated with a node might be color, shape, and size. VisualProperties for an edge might be color, width, and dash pattern. The VisualProperty interface allows Cytoscape to treat different aspects of the visualization in uniform ways.

The publicly available VisualProperties in the system are accessed through the BasicVisualLexicon, however not all RenderingEngines support all VisualProperties and some RenderingEngines supply their own VisualProperties.

Visual Mapping

API Jar: vizmap-api, vizmap-gui-api

Namespace: org.cytoscape.view.vizmap

The Cytoscape VizMapper provides the abilty to connect your network topology with your attribute table. With the VizMapper you can visualize your attribute data as visual properties of your network.

A VisualStyle describes a set of VisualMappingFunctions. A VisualMappingFunction describes how one attribute (i.e. column in a table) is mapped to one VisualProperty of a network view. The VisualMappingManager contains the set of available VisualStyles and contains a mapping of which VisualStyle is currently being applied to which CyNetworkView.

Presentation

API Jar: presentation-api

Namespace: org.cytoscape.view.presentation

The Presentation API is deliberately minimal. Our goal has been to make presentation implementations easily replaceable. An implementation of the Presentation API does only a few things: provide basic graphics support (for printing, icon generation, etc.) and as providing a list of VisualProperties. Depending on which rendering engine is being used, different VisualProperties may or may not be supported (e.g. a NODE_DEPTH visual property might exist in a 3D renderer, but not a 2D renderer).

The Presentation API provides a basic set of pre-defined VisualProperties that most rendering engines can be expected to implement, however some RenderingEngines may provide new VisualProperties while not supporting others.

Work, Tasks, and Tunables

API Jar: work-api, work-swing-api, core-task-api

Namespace: org.cytoscape.work, org.cytoscape.task

The Work API defines the fundamental unit of work in Cytoscape, the Task. All Task objects are created by TaskFactory singleton objects. The Task or Tasks created by a TaskFactory are executed by the TaskManager. The TaskFactory API has been extended in several ways in the core-task-api to provide a framework for commonly used, specialized tasks (e.g. NetworkTask, NetworkViewTask, NodeViewTask, etc.).

User inputs to !Task/TaskFactory objects are specified using the @Tunable annotation. By annotating fields and methods in the Task or TaskFactory objects, users will be prompted to enter information such as file names that only they can specify.

Using Tunable annotations with !Task/TaskFactory objects is the preferred way of caputuring user input in Cytoscape because Tunables do not bind users to a Swing user interface!

Core Task API also provides a number of specific TaskFactory service interfaces which are meant to perform specific tasks (e.g. load a network from a file) and that can be used by App writers. This should allow common tasks to be written once and reused easily.

Layouts

API Jar: layout-api

Namespace: org.cytoscape.view.layout

The Layout API provides a small extension to the NetworkViewTaskFactory interface as well a several abstract and utility classes. The goal is allow algorithm writers to focus on writing a layout algorithm that works for a connected graph and then allow the abstract class to handle the execution for the entire network and things like undo.

Properties

API Jar: property-api

Namespace: org.cytoscape.property

The CyProperty interface is simply an OSGi service interface that provides access to properties of different types. In most cases, the CyProperty interface will wrap a java.util.Properties object, but in other cases it may contain a specialized objects for Bookmarks and the like.

Sessions

API Jar: session-api

Namespace: org.cytoscape.session

The Session API is where to look if you need to save data in a session file, or if you want to be notified (e.g. when you need to initialize something) that a session is being saved or loaded.

Application

API Jar: application-api

Namespace: org.cytoscape.application

The Application API also includes the CyApplicationManager which tracks the current network and current network view.

Swing Application

API Jar: swing-application-api

Namespace: org.cytoscape.application.swing

The Swing Application API is where to look for the Swing hooks to get your code displaying properly in Cytoscape. If you need access to the desktop !JFrame or want to add a CytoPanel (using the CytoPanelComponent interface), this is where to go. The CyAction provides a mechanism for adding menu items and toolbar actions, however this approach is only recommended when complicated, custom GUIs are necessary.

Using any classes in the Swing Application API limits your code to working with the desktop application. This means that if you intend for your algorithm to work from the command line or in some other context, it would be much better to write your code in terms of the work- or core-task-api.

IO

API Jar: io-api, webservice-api

Namespace: org.cytoscape.io

The IO interfaces define how different types of files can be read and written. Third parties may register readers and writers for new file types (e.g. a new network file type) such that the reader/writer integrates cleanly with all of the other readers/writers available in the system.

We also provide a web service API, so that web services may also be cleanly integrated with the rest of Cytoscape.

App

API Jar: app-api

Namespace: org.cytoscape.app

The App API is provided to make developing apps as easy as possible for developers with minimal Java programming experience. The App API assumes no knowledge of OSGi, Spring, or Maven. The API defines only two classes, the abstract CyApp, which app authors extend and the CyAppAdapter, which provides access to all manager and factory classes in Cytoscape that are normally provided as OSGi services.

MoinMoin Appliance - Powered by TurnKey Linux