Cytoscape 2.8.0 API

cytoscape.data
Interface CyAttributes

All Known Implementing Classes:
CyAttributesImpl

public interface CyAttributes

CyAttributes provides access to network, node, and edge attributes within Cytoscape.

CyAttributes is a replacement for GraphObjAttributes, which will be officially removed from the Cytoscape core in September, 2006.

Basic Concepts:

Each network, node, and edge within Cytoscape can be annotated with one or more attributes. For example, a node representing a protein could have attributes for description, species, NCBI Gene ID, UniProt ID, etc. These attributes are set and retrieved via the CyAttributes interface.

Global Attributes:

There are three sets of global attributes, one for networks, one for nodes, and one for edges. To access these global attributes, use:

Unique Identifiers:

CyAttributes uses unique identifiers to attach attributes to specific nodes and edges. The unique identifiers for nodes and edges are available via the getIdentifier() method:

Data Type Restrictions:

CyAttributes uses a MultiHashMap data structure, which restricts attribute values to four data types: Boolean, Integer, Double, and String. It does not store arbitrary Java Objects. We do this for three reasons:

Getting / Setting Attributes: An Overview

There are three ways to get/set attributes. They are (in order of increasing complexity): Each of these approaches is detailed below.

Getting / Setting Individual Values:

This is the simplest option. Attributes are restricted to the following four types: There are getters and setters for each of these four types. For example, the following code snippet sets and gets an Integer attribute value:
 cyAttributes.setAttribute (node.getIdentifier(),
     "Rank", new Integer(3));
 Integer value = cyAttributes.getIntegerAttribute
     (node.getIdentifier(), "Rank");
 

Getting / Setting Simple Lists:

A 'simple' list is defined as follows: In other words, a list of three Integer Objects is a simple list, whereas a mix of two Integer and one Boolean Object is not.

The following code snippet illustrates how to set a simple list of three Integer Objects:

 ArrayList list = new ArrayList();
 list.add (new Integer(1));
 list.add (new Integer(22));
 list.add (new Integer(5));
 cyAttributes.setList (node.getIdentifier(),
     "Rank List", list).
 
At run-time, the setList method will check that all items in the list are of the same type, and are chosen from the following list: Boolean, Integer, Double or String. If these criteria are not met, an IllegalArgumentException will be thrown.

To get a simple list, use the getListAttribute(String, String) method.

Getting / Setting Simple Maps:

A 'simple' map is defined as follows: In other words, a map that contains three Integer values is a simple map, whereas a map that contains two Integer values and one Boolean value is not.

The following code snippet illustrates how to set a simple map of three String Objects:

 Map map = new HashMap();
 map.put("name", "Reactome");
 map.put("url", "http://www.reactome.org");
 map.put("description", "Reactome - a knowledgebase of "
     + "biological processes");
 cyAttributes.setMapAttribute(node.getIdentifier(),
     "external_db", map);
 
To get a simple map, use the getMapAttribute(String, String) method.

Working with Fixed Attribute Types:

Each attribute is bound to a specific data type, and this data type is set and fixed the first time the attribute is used. For example, in Plugin 1, the following code sets "RANK" to be of type Integer:
 cyAttributes.setAttribute (node.getIdentifier(), "Rank", new Integer(3));
 
Later on, Plugin 2 executes the following code:
 cyAttributes.setAttribute (node.getIdentifier(), "Rank",
     new String("Three"));
 
We are now attempting to set "RANK" to a String value, but "RANK" is already fixed as an Integer data type. Hence, the call is considered invalid, and an IllegalArgumentException will be thrown.

The same situation can occur with simple lists and simple maps. For example, if PlugIn 1 defines a simple list of all Integer values, and PlugIn 2 attempts to re-use this attribute with a list of Double values, the call is considered invalid, and an IllegalArgumentException will be thrown.

To prevent this type of problem, use getType(String) to determine the attribute's data type before setting any new attributes.

To reset an attribute's data type, use deleteAttribute(String). Note that calling this method will delete all attributes with this name, preparing the way for a clean slate. Please use with caution!

Working with Arbitrarily Complex Data Structures:

CyAttributes uses a MultiHashMap data structure to store attributes. This data structure enables you to store arbitrarily complex trees of data, but restricts the tree to Objects of type: Boolean, Integer, Double or String.

If you wish to store arbitarily complex data structures (e.g. anything more complicated than a simple list or a simple map), you can do so by obtaining the MultiHashMap via getMultiHashMap(), and getMultiHashMapDefinition(), and working on the data structure directly. Complete information is available in the MultiHashMap javadocs.

Listening for Attribute Events:

As noted above, CyAttributes uses a MultiHashMap data structure to store attributes. To listen to attribute events, first obtain the MultiHashMap via getMultiHashMap(), and then register a listener via MultiHashMap.addDataListener(cytoscape.data.attr.MultiHashMapListener).

Note that calls to setListAttribute(String, String, java.util.List) and setMapAttribute(String, String, java.util.Map) result in many calls to the MultiHashMap object. For example, if you have five elements in a List, the implementation code makes five calls to the MultiHashMap, and you will therefore be notified of five separate events, rather than one global list event.

Setting attribute descriptions and user interaction flags:

Starting in Cytoscape 2.4, you can add human readable text descriptions to attributes. These descriptions are automatically presented to the end user via various user interface elements, including the default node/edge attribute browser and via the QuickFind configuration panel. To set an attribute description, use the setAttributeDescription(String, String) method. To retrieve an attribute description, use the getAttributeDescription(String) method.

Starting in Cytoscape 2.4, you can also flag attributes as visible / hidden or editable / non-editable by the end user. User interface elements use these attribute flags to determine user interactivity. For example, the default attribute browser will hide all attributes marked as hidden, and will restrict users to edit only those attributes marked as editable. By default, all attributes are visible and editable. Therefore, you only need to interact with this portion of the API if you want to specifically hide certain attributes or mark certain attributes as non-editable.

To set an attribute as invisible, use the setUserVisible(String, boolean) method and set to false.

To set an attribute as non-editable, use the setUserEditable(String, boolean) method and set to false.

Note: CyAttributes does not enforce these user interfaction flags. Rather, relevant user interface (UI) element(s) must query CyAttributes, and enforce the interaction flags themselves.

Author:
Cytoscape Development Team

Field Summary
static byte TYPE_BOOLEAN
          This type corresponds to java.lang.Boolean.
static byte TYPE_COMPLEX
          This type corresponds to a data structure of arbitrary complexity, e.g.
static byte TYPE_FLOATING
          This type corresponds to java.lang.Double.
static byte TYPE_INTEGER
          This type corresponds to java.lang.Integer.
static byte TYPE_SIMPLE_LIST
          This type corresponds to a 'simple' list.
static byte TYPE_SIMPLE_MAP
          This type corresponds to a 'simple' hash map.
static byte TYPE_STRING
          This type corresponds to java.lang.String.
static byte TYPE_UNDEFINED
          This type corresponds to an attribute which has not been defined.
 
Method Summary
 boolean deleteAttribute(String attributeName)
          Deletes the specified attribute.
 boolean deleteAttribute(String id, String attributeName)
          Deletes the id/attributeName pair.
 Object getAttribute(String id, String attributeName)
          Gets an Object value at the specified id/attributeName.
 String getAttributeDescription(String attributeName)
          Gets the human readable description of a specific attribute.
 List getAttributeList(String id, String attributeName)
          Deprecated. Use getListAttribute() instead. Will be removed 11/2007.
 Map getAttributeMap(String id, String attributeName)
          Deprecated. Use getMapAttribute() instead. Will be removed 11/2007.
 String[] getAttributeNames()
          Gets an array of all attribute names.
 Boolean getBooleanAttribute(String id, String attributeName)
          Gets a Boolean value at the specified id/attributeName.
 Double getDoubleAttribute(String id, String attributeName)
          Gets a Double value at the specified id/attributeName.
 Equation getEquation(String id, String attributeName)
           
 Integer getIntegerAttribute(String id, String attributeName)
          Gets an Integer value at the specified id/attributeName.
 String getLastEquationError()
          Returns any attribute-equation related error message after a call to getAttribute() or getXXXAttribute().
 List getListAttribute(String id, String attributeName)
          Gets a 'simple' list of attributes for the id/attributeName pair.
 byte getListElementType(String attributeName)
          Gets the member data type of the specified simple list attribute.
 Map getMapAttribute(String id, String attributeName)
          Gets a 'simple' map of attribute values.
 MultiHashMap getMultiHashMap()
          Gets the MultiHashMap Object, where we store attribute values.
 MultiHashMapDefinition getMultiHashMapDefinition()
          Gets the MultiHashMapDefinition Object, where we store attribute definitions.
 String getStringAttribute(String id, String attributeName)
          Gets a String value at the specified id/attributeName.
 byte getType(String attributeName)
          Gets the data type of the specified attribute.
 boolean getUserEditable(String attributeName)
          Returns the boolean indicating whether this attribute should be editable by the end user or not.
 boolean getUserVisible(String attributeName)
          Returns the boolean indicating whether the specified attribute should be made visible to the end user or not.
 boolean hasAttribute(String id, String attributeName)
          Determines if the specified id/attributeName pair exists.
 void setAttribute(String id, String attributeName, Boolean value)
          Sets an id/attributeName pair of type Boolean.
 void setAttribute(String id, String attributeName, Double value)
          Sets an id/attributeName pair of type Double.
 void setAttribute(String id, String attributeName, Equation equation)
           
 void setAttribute(String id, String attributeName, Equation equation, byte dataType)
           
 void setAttribute(String id, String attributeName, Integer value)
          Sets an id/attributeName pair of type Integer.
 void setAttribute(String id, String attributeName, String value)
          Sets an id/attributeName pair of type String.
 void setAttributeDescription(String attributeName, String description)
          Sets a human readable description of a specific attribute.
 void setListAttribute(String id, String attributeName, Equation equation)
          Sets a simple list of attributes.
 void setListAttribute(String id, String attributeName, List list)
          Sets a simple list of attributes.
 void setMapAttribute(String id, String attributeName, Map map)
          Sets a 'simple' map of attribute values.
 void setUserEditable(String attributeName, boolean value)
          Sets the specified boolean to indicate whether or not the specified attribute should be editable by the end user.
 void setUserVisible(String attributeName, boolean value)
          Sets the specified boolean to indicate whether or not the specified attribute should be made visible to the end user.
 

Field Detail

TYPE_BOOLEAN

static final byte TYPE_BOOLEAN
This type corresponds to java.lang.Boolean.

See Also:
Constant Field Values

TYPE_FLOATING

static final byte TYPE_FLOATING
This type corresponds to java.lang.Double.

See Also:
Constant Field Values

TYPE_INTEGER

static final byte TYPE_INTEGER
This type corresponds to java.lang.Integer.

See Also:
Constant Field Values

TYPE_STRING

static final byte TYPE_STRING
This type corresponds to java.lang.String.

See Also:
Constant Field Values

TYPE_SIMPLE_LIST

static final byte TYPE_SIMPLE_LIST
This type corresponds to a 'simple' list.

A 'simple' list is defined as follows:

See Also:
Constant Field Values

TYPE_SIMPLE_MAP

static final byte TYPE_SIMPLE_MAP
This type corresponds to a 'simple' hash map.

A 'simple' map is defined as follows:

See Also:
Constant Field Values

TYPE_COMPLEX

static final byte TYPE_COMPLEX
This type corresponds to a data structure of arbitrary complexity, e.g. anything more complex than a 'simple' list or a 'simple' map.

For complete details, refer to the class comments, or getMultiHashMap().

See Also:
Constant Field Values

TYPE_UNDEFINED

static final byte TYPE_UNDEFINED
This type corresponds to an attribute which has not been defined.

See Also:
Constant Field Values
Method Detail

getAttributeNames

String[] getAttributeNames()
Gets an array of all attribute names.

Returns:
an array of String Objects.

setAttributeDescription

void setAttributeDescription(String attributeName,
                             String description)
Sets a human readable description of a specific attribute.

Parameters:
attributeName - attribute name.
description - human readable description of attribute. used for display to end-user.

getAttributeDescription

String getAttributeDescription(String attributeName)
Gets the human readable description of a specific attribute.

Parameters:
attributeName - attribute name.
Returns:
human readable description of attribute or null (if no description has been specified).

setUserVisible

void setUserVisible(String attributeName,
                    boolean value)
Sets the specified boolean to indicate whether or not the specified attribute should be made visible to the end user.

By default, all attributes are visible.

Note: CyAttributes does not actually enforce user visibility. Rather, relevant user interface (UI) element(s) must query CyAttributes, and enforce the visibility flag themselves.

Parameters:
attributeName - Attribute name.
value - the boolean to be set. true indicates that the attribute should be made visible to the end user. false indicates that the attribute should not be made visible to the end user.

getUserVisible

boolean getUserVisible(String attributeName)
Returns the boolean indicating whether the specified attribute should be made visible to the end user or not.

By default, all attributes are visible.

Note: CyAttributes does not actually enforce user visibility. Rather, relevant user interface (UI) element(s) must query CyAttributes, and enforce the visibility flag themselves.

Parameters:
attributeName - Attribute name.
Returns:
true indicates that the attribute should be made visible to the end user. false indicates that the attribute should not be made visible to the end user.

setUserEditable

void setUserEditable(String attributeName,
                     boolean value)
Sets the specified boolean to indicate whether or not the specified attribute should be editable by the end user.

By default, all attributes are editable.

Note: CyAttributes does not actually enforce restrictions on user editing of attributes. Rather, relevant user interface (UI) element(s) must query CyAttributes, and enforce the editing requirements themselves.

Parameters:
attributeName - Attribute name.
value - the boolean to be set. true indicates that the attribute should be editable by the end user. false indicates that the attribute should not be editable by the end user.

getUserEditable

boolean getUserEditable(String attributeName)
Returns the boolean indicating whether this attribute should be editable by the end user or not.

By default, all attributes are editable.

Note: CyAttributes does not actually enforce restrictions on user editing of attributes. Rather, relevant user interface (UI) element(s) must query CyAttributes, and enforce the editing requirements themselves.

Parameters:
attributeName - Attribute name.
Returns:
true indicates that the attribute should be editable by the end user. false indicates that the attribute should not be editable by the end user.

hasAttribute

boolean hasAttribute(String id,
                     String attributeName)
Determines if the specified id/attributeName pair exists.

Parameters:
id - unique identifier.
attributeName - attribute name.
Returns:
true or false.

setAttribute

void setAttribute(String id,
                  String attributeName,
                  Boolean value)
                  throws IllegalArgumentException
Sets an id/attributeName pair of type Boolean.

Parameters:
id - unique identifier.
attributeName - attribute name.
value - boolean value.
Throws:
IllegalArgumentException - Indicates that this attribute has already been defined with a data type, and this data type is not of type: TYPE_BOOLEAN.

setAttribute

void setAttribute(String id,
                  String attributeName,
                  Integer value)
                  throws IllegalArgumentException
Sets an id/attributeName pair of type Integer.

Parameters:
id - unique identifier.
attributeName - attribute name.
value - integer value.
Throws:
IllegalArgumentException - Indicates that this attribute has already been defined with a data type, and this data type is not of type: TYPE_INTEGER.

setAttribute

void setAttribute(String id,
                  String attributeName,
                  Double value)
                  throws IllegalArgumentException
Sets an id/attributeName pair of type Double.

Parameters:
id - unique identifier.
attributeName - attribute name.
value - double value.
Throws:
IllegalArgumentException - Indicates that this attribute has already been defined with a data type, and this data type is not of type: TYPE_FLOATING.

setAttribute

void setAttribute(String id,
                  String attributeName,
                  String value)
                  throws IllegalArgumentException
Sets an id/attributeName pair of type String.

Parameters:
id - unique identifier.
attributeName - attribute name.
value - string value.
Throws:
IllegalArgumentException - Indicates that this attribute has already been defined with a data type, and this data type is not of type: TYPE_STRING.

setAttribute

void setAttribute(String id,
                  String attributeName,
                  Equation equation)
Parameters:
id - unique identifier.
attributeName - attribute name.
equation - an attribute equation

setAttribute

void setAttribute(String id,
                  String attributeName,
                  Equation equation,
                  byte dataType)
Parameters:
id - unique identifier.
attributeName - attribute name.
equation - an attribute equation
dataType - must be one of MultiHashMapDefinition.TYPE_{BOOLEAN,STRING,INTEGER, or FLOATING_POINT}

getBooleanAttribute

Boolean getBooleanAttribute(String id,
                            String attributeName)
                            throws ClassCastException
Gets a Boolean value at the specified id/attributeName.

Parameters:
id - unique identifier.
attributeName - attribute name.
Returns:
Boolean object, or null if no id/attributeName pair is found.
Throws:
ClassCastException - Indicates that the specified attribute is not of type: TYPE_BOOLEAN.

getIntegerAttribute

Integer getIntegerAttribute(String id,
                            String attributeName)
                            throws ClassCastException
Gets an Integer value at the specified id/attributeName.

Parameters:
id - unique identifier.
attributeName - attribute name.
Returns:
Integer object, or null if no id/attributeName pair is found.
Throws:
ClassCastException - Indicates that the specified attribute is not of type: TYPE_INTEGER.

getDoubleAttribute

Double getDoubleAttribute(String id,
                          String attributeName)
                          throws ClassCastException
Gets a Double value at the specified id/attributeName.

Parameters:
id - unique identifier.
attributeName - attribute name.
Returns:
Double object, or null if no id/attributeName pair is found..
Throws:
ClassCastException - Indicates that the specified attribute is not of type: TYPE_FLOATING.

getStringAttribute

String getStringAttribute(String id,
                          String attributeName)
                          throws ClassCastException
Gets a String value at the specified id/attributeName.

Parameters:
id - unique identifier.
attributeName - attribute name.
Returns:
String object, or null if no id/attributeName pair is found.
Throws:
ClassCastException - Indicates that the specified attribute is not of type: TYPE_STRING.

getAttribute

Object getAttribute(String id,
                    String attributeName)
Gets an Object value at the specified id/attributeName. This is a convenience method for those situations when attribute type isn't relevant. You should NOT use this method and cast the result to the type of attribute. Instead, just call the appropriate get*Attribute method.

Parameters:
id - unique identifier.
attributeName - attribute name.
Returns:
Object, or null if no id/attributeName pair is found.

getType

byte getType(String attributeName)
Gets the data type of the specified attribute.

Parameters:
attributeName - Attribute Name.
Returns:
one of: TYPE_BOOLEAN, TYPE_INTEGER, TYPE_FLOATING, TYPE_STRING, TYPE_SIMPLE_LIST, TYPE_SIMPLE_MAP, TYPE_COMPLEX, TYPE_UNDEFINED.

getListElementType

byte getListElementType(String attributeName)
Gets the member data type of the specified simple list attribute.

Parameters:
attributeName - the name of a simple list attribute
Returns:
one of: TYPE_BOOLEAN, TYPE_INTEGER, TYPE_FLOATING, TYPE_STRING

deleteAttribute

boolean deleteAttribute(String id,
                        String attributeName)
Deletes the id/attributeName pair.

Parameters:
id - unique identifier.
attributeName - attribute name.
Returns:
true indicates attribute was successfully removed.

deleteAttribute

boolean deleteAttribute(String attributeName)
Deletes the specified attribute.

Calling this method deletes all id/attributeName pairs with this attributeName, and resets the specified attribute data type to: TYPE_UNDEFINED. Please use with caution!

Parameters:
attributeName - attribute name.
Returns:
true indicates attribute was successfully reset.

setListAttribute

void setListAttribute(String id,
                      String attributeName,
                      List list)
                      throws IllegalArgumentException
Sets a simple list of attributes.

A simple list is defined as follows:

If the above requirements are not met, an IllegalArgumentException will be thrown.

Implementation note: calling this method results in many calls to the MultiHashMap back-end data store. For example, if you have five elements in a List, the implementation code makes five calls to the MultiHashMap. Therefore, if you are listening to MultiHashMap events, you will be notified of five separate events, rather than one global list event.

Parameters:
id - unique identifier.
list - attribute name.
list - List Object.
Throws:
IllegalArgumentException - Simple List requirements have not been met, or this attribute has already been defined with a data type, and this data type is not of type: TYPE_SIMPLE_LIST.

setListAttribute

void setListAttribute(String id,
                      String attributeName,
                      Equation equation)
                      throws IllegalArgumentException
Sets a simple list of attributes.

A simple list is defined as follows:

If the above requirements are not met, an IllegalArgumentException will be thrown.

Implementation note: calling this method results in many calls to the MultiHashMap back-end data store. For example, if you have five elements in a List, the implementation code makes five calls to the MultiHashMap. Therefore, if you are listening to MultiHashMap events, you will be notified of five separate events, rather than one global list event.

Parameters:
id - unique identifier.
list - attribute name.
list - List Object.
equation - an attribute equation
Throws:
IllegalArgumentException - Simple List requirements have not been met, or this attribute has already been defined with a data type, and this data type is not of type: TYPE_SIMPLE_LIST.

getAttributeList

List getAttributeList(String id,
                      String attributeName)
                      throws ClassCastException
Deprecated. Use getListAttribute() instead. Will be removed 11/2007.

Throws:
ClassCastException

getListAttribute

List getListAttribute(String id,
                      String attributeName)
                      throws ClassCastException
Gets a 'simple' list of attributes for the id/attributeName pair.

A 'simple' list is defined as follows:

Note: The returned List is useful for read operations only. If you add, edit, or delete elements within this list, these changes will not be stored, unless you explicitly call setListAttribute() again. For example:

 List list = nodeAttributes.getListAttribute(id, attributeName);

 //  Add new item
 list.add(new String("Hello, World");

 //  Save modified list back
 nodeAttributes.setListAttribute(id, attributeName, list);
 

Parameters:
id - unique identifier.
attributeName - attribute name.
Returns:
List object.
Throws:
ClassCastException - Indicates that the specified attribute is not of type: TYPE_SIMPLE_LIST.

setMapAttribute

void setMapAttribute(String id,
                     String attributeName,
                     Map map)
                     throws IllegalArgumentException
Sets a 'simple' map of attribute values.

A 'simple' map is defined as follows:

If the above requirements are not met, an IllegalArgumentException will be thrown.

Implementation note: calling this method results in many calls to the MultiHashMap back-end data store. For example, if you have five elements in a Map, the implementation code makes five calls to the MultiHashMap. Therefore, if you are listening to MultiHashMap events, you will be notified of five separate events, rather than one global map event.

Parameters:
id - unique identifier.
attributeName - attribute name.
map - Map Object.
Throws:
IllegalArgumentException - Simple Map requirements have not been met or this attribute has already been defined with a data type, and this data type is not of type: TYPE_SIMPLE_MAP.

getAttributeMap

Map getAttributeMap(String id,
                    String attributeName)
Deprecated. Use getMapAttribute() instead. Will be removed 11/2007.


getMapAttribute

Map getMapAttribute(String id,
                    String attributeName)
Gets a 'simple' map of attribute values.

A 'simple' map is defined as follows:

Note: The returned Map is useful for read operations only. If you add, edit, or delete elements within this Map, these changes will not be stored, unless you explicitly call setMapAttribute() again. For example:

 Map map = nodeAttributes.getMapAttribute(id, attributeName);

 //  Add new item
 map.put(new String("Message"), new String("Hello, World"));

 //  Save modified map back
 nodeAttributes.setMapAttribute(id, attributeName, map);
 

Parameters:
id - unique identifier.
attributeName - attribute name.
Returns:
Map Object.
Throws:
ClassCastException - Indicates that the specified attribute is not of type: TYPE_HASH_MAP.

getMultiHashMap

MultiHashMap getMultiHashMap()
Gets the MultiHashMap Object, where we store attribute values.

By using MultiHashMap and MultiHashMapDefinition directly, you can store arbitrarily complex data structures. Recommended for advanced coders only.

Returns:
MultiHashMap Object.

getMultiHashMapDefinition

MultiHashMapDefinition getMultiHashMapDefinition()
Gets the MultiHashMapDefinition Object, where we store attribute definitions.

By using MultiHashMap and MultiHashMapDefinition directly, you can store arbitrarily complex data structures (e.g. anything more complicated that 'simple' lists and 'simple' maps). Recommended for advanced coders only.

Returns:
MultiHashMapDefinition Object.

getEquation

Equation getEquation(String id,
                     String attributeName)
Returns:
the equation associated with an attribute or null if there is no equation associated with it

getLastEquationError

String getLastEquationError()
Returns any attribute-equation related error message after a call to getAttribute() or getXXXAttribute(). N.B., the last error message will be cached!

Returns:
an error message or null if the last call to getAttribute() did not result in an equation related error

Cytoscape 2.8.0 API

Copyright 2010 Cytoscape Consortium. All rights reserved.