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:

• Cytoscape.getNetworkAttributes()
• 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 networks, use CyNetwork.getIdentifier().
• 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 network/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 getListAttribute(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.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. 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.
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.
Integer	getIntegerAttribute(String id, String attributeName) Gets an Integer value at the specified id/attributeName.
List	getListAttribute(String id, String attributeName) Gets a 'simple' list of attributes for the id/attributeName pair.
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, 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	setAttributeList(String id, String attributeName, List list) Deprecated. Use setListAttribute() instead. Will be removed 11/2007.
void	setAttributeMap(String id, String attributeName, Map map) Deprecated. Use setMapAttribute() instead. Will be removed 11/2007.
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:

• 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

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

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.

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.

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.

setAttributeList

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

Deprecated. Use setListAttribute() instead. Will be removed 11/2007.

Throws:

IllegalArgumentException

setListAttribute

void setListAttribute(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.

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.

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:

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

setAttributeMap

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

Deprecated. Use setMapAttribute() instead. Will be removed 11/2007.

Throws:

IllegalArgumentException

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:

• 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

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:

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