## page was renamed from Cytoscape_3/Background/APIOverview ## page was renamed from RFC Template || '''Cytoscape 3 Documentation''' : Overview of the API|| '''Editor(s)''': MikeSmoot || '''Date''': February 24th 2011 ||'''Status''': First version || <> === 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. A view for a !CyNetwork is a !CyNetworkView which extends View 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.