cytoscape.data
Interface CyAttributes

public interface CyAttributes

CyAttributes provides access to 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 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 two sets of global attributes, one for nodes, and one for edges. To access these global attributes, use:

• Cytoscape.getNodeAttributes()
• Cytoscape.getEdgeAttributes()

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:

• For nodes, use CyNode.getIdentifier().
• For edges, use CyEdge.getIdentifier().

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:

• We want to provide complete import/export of all attribute values, without having to rely on Java serialization.
• We want to enable inter-plugin communication, such that plugins can share attribute data without having to agree to use some predefined or custom data structure ahead of time.
• We want to build a universal node/edge attribute browser.

Getting / Setting Attributes: An Overview

There are three ways to get/set attributes. They are (in order of increasing complexity):

• Getting / setting individual values.
• Getting / setting 'simple' lists and 'simple' maps.
• Getting / setting arbitrarily complex data structures.

Each of these approaches is detailed below.

Getting / Setting Individual Values:

This is the simplest option. Attributes are restricted to the following four types:

• Boolean, Integer, Double, String

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:

• All items within the list are of the same type, and are chosen from one of the following: Boolean, Integer, Double or String.

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 getAttributeList(String, String) method.

Getting / Setting Simple Maps:

A 'simple' map is defined as follows:

• All keys within the map are of type: String.
• All values within the map are of the same type, and are chosen from one of the following: Boolean, Integer, Double or String.

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.setAttributeMap(node.getIdentifier(),
     "external_db", map);
 

To get a simple map, use the getAttributeMap(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 setAttributeList(String, String, java.util.List) and setAttributeMap(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, rathern than one global list event.

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. anything more complex than a 'simple' list or a 'simple' map.
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.
List	getAttributeList(String id, String attributeName) Gets a 'simple' list of attributes for the id/attributeName pair.
Map	getAttributeMap(String id, String attributeName) Gets a 'simple' map of attribute values.
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.
Integer	getIntegerAttribute(String id, String attributeName) Gets an Integer value at the specified id/attributeName.
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	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, 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	setAttributeList(String id, String attributeName, List list) Sets a simple list of attributes.
void	setAttributeMap(String id, String attributeName, Map map) Sets a 'simple' map of attribute values.

Field Detail

TYPE_BOOLEAN

public static final byte TYPE_BOOLEAN

This type corresponds to java.lang.Boolean.

See Also:

Constant Field Values

TYPE_FLOATING

public static final byte TYPE_FLOATING

This type corresponds to java.lang.Double.

See Also:

Constant Field Values

TYPE_INTEGER

public static final byte TYPE_INTEGER

This type corresponds to java.lang.Integer.

See Also:

Constant Field Values

TYPE_STRING

public static final byte TYPE_STRING

This type corresponds to java.lang.String.

See Also:

Constant Field Values

TYPE_SIMPLE_LIST

public static final byte TYPE_SIMPLE_LIST

This type corresponds to a 'simple' list.

A 'simple' list is defined as follows:

• All items within the list are of the same type, and are chosen from one of the following: Boolean, Integer, Double or String.

See Also:

Constant Field Values

TYPE_SIMPLE_MAP

public static final byte TYPE_SIMPLE_MAP

This type corresponds to a 'simple' hash map.

A 'simple' map is defined as follows:

• All keys within the map are of type: String.
• All values within the map are of the same type, and are chosen from one of the following: Boolean, Integer, Double or String.

See Also:

Constant Field Values

TYPE_COMPLEX

public 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

public static final byte TYPE_UNDEFINED

This type corresponds to an attribute which has not been defined.

See Also:

Constant Field Values

Method Detail

getAttributeNames

public String[] getAttributeNames()

Gets an array of all attribute names.

Returns:

an array of String Objects.

hasAttribute

public 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

public 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

public 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

public 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

public 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.

getBooleanAttribute

public 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

public 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

public 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

public 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.

getType

public 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.

deleteAttribute

public 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

public 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.

setAttributeList

public void setAttributeList(String id,
                             String attributeName,
                             List list)
                      throws IllegalArgumentException

Sets a simple list of attributes.

A simple list is defined as follows:

• All items within the list are of the same type, and are chosen from one of the following: Boolean, Integer, Double or String.

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.

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

public List getAttributeList(String id,
                             String attributeName)
                      throws ClassCastException

Gets a 'simple' list of attributes for the id/attributeName pair.

A 'simple' list is defined as follows:

• All items within the list are of the same type, and are chosen from one of the following: Boolean, Integer, Double or String.

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 setAttributeList() again. For example:

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

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

 //  Save modified list back
 nodeAttributes.setAttributeList(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.

setAttributeMap

public void setAttributeMap(String id,
                            String attributeName,
                            Map map)
                     throws IllegalArgumentException

Sets a 'simple' map of attribute values.

A 'simple' map is defined as follows:

• All keys within the map are of type: String.
• All values within the map are of the same type, and are chosen from one of the following: Boolean, Integer, Double or String.

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

public Map getAttributeMap(String id,
                           String attributeName)

Gets a 'simple' map of attribute values.

A 'simple' map is defined as follows:

• All keys within the map are of type: String.
• All values within the map are of the same type, and are chosen from one of the following: Boolean, Integer, Double or String.

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 setAttributeMap() again. For example:

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

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

 //  Save modified map back
 nodeAttributes.setAttributeMap(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

public 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

public 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.