cytoscape.layout
Class Tunable

java.lang.Object
  cytoscape.layout.Tunable

All Implemented Interfaces:

ActionListener, FocusListener, ItemListener, EventListener, ChangeListener, ListSelectionListener

public class Tunable
extends Object
implements FocusListener, ChangeListener, ActionListener, ItemListener, ListSelectionListener

Tunables are typed objects that maintain properties and an easy way to generate a settings panel to allow user manipulation of them.

A Tunable is a utility that serves two important functions:

1. It provides a convenient way to read, set, and save properties that can be used to influence algorithms or presentation
2. It provides a quick way to present an interface to the user to allow them to update and change those properties.

Tunables were originally written to support the needs of users of Cytoscape's various layout algorithms (see CyLayoutAlgorithm) to access the various tunable parameters in the algorithms. In general, Tunables are collected together by the ModuleProperties system. See LayoutProperties as a good example.

Basic Concepts

A Tunable can be thought of as a typed variable that knowns how to initialize and save itself as a Cytoscape property, and present itself to the user for input. All tunables have the following information:

• name: the name of the tunable, which is used to access the tunable and to save it as a property.
• description: the description of the tunable, which is displayed to the user for input.
• type: the type of the tunable, which must be one of INTEGER, DOUBLE, BOOLEAN, STRING, NODEATTRIBUTE, EDGEATTRIBUTE, LIST, GROUP, or BUTTON.
• value: this is set in construction as the initial value, but is also maintained as the value loaded from the Cytoscape properties or entered by the user. The type of this value depends on the type of the Tunable:
  • INTEGER: Integer
  • DOUBLE: Double
  • BOOLEAN: Boolean
  • STRING: String
  • NODEATTRIBUTE: String, or if MULTISELECT, comma-separated list of Strings representing the selected attributes
  • EDGEATTRIBUTE: String, or if MULTISELECT, comma-separated list of Strings representing the selected attributes
  • LIST: Integer, or if MULTISELECT, comma-separated list of integers representing the selected attributes
• lowerBound: for INTEGER or DOUBLE tunables, the lowerBound is an optional Integer or Double value representing the smallest integer or double that constitutes a legal input. For LIST tunables, the lowerBound is an array of Objects representing the list to choose from, and for NODEATTRIBUTE, and EDGEATTRIBUTE tunables, lowerBound is an optional array of Strings that will prefix the list of attributes. This allows users to provide their own overrides into the list. For GROUP tunables, that have the COLLAPSABLE flag set, this is a Boolean value that indicates whether the group is collapsed or expanded.
• upperBound: for INTEGER or DOUBLE tunables, the upperBound is an optional Integer or Double value representing the larget integer or double that constitutes a legal input.
• flag: Flags provide hints as to the desired presentation of the Tunable or restrictions on the values. Currently, the flags include: IMMUTABLE, which prevents user entry; MULTISELECT, which presents lists as a JList rather than JComboBox; NOINPUT, which indicates that this tunable should not be presented to the user; NUMERICATTRIBUTE, which indicates for attribute lists that only numeric attributes should be used; and USESLIDER, which suggests to the UI to use a slider to present this value.

Common Usage

The most common usage of Tunables is to provide a list of values that influences the presentation or calculation of a layout, clustering algorithm, etc. When combined with LayoutProperties, tunables provide a very quick way to put together a user interface and get the results from it. A common approach would be for the algorithm to include a section of code that creates all of the Tunables associated with the algorithm's parameters. For example this section from csplugins.layout.algorithms.force#ForceDirectedLayout:

     layoutProperties = new LayoutProperties("my_module");
     layoutProperties.add(new Tunable("standard", "Standard settings",
                          Tunable.GROUP, new Integer(2)));

     layoutProperties.add(new Tunable("partition", "Partition graph before layout",
                          Tunable.BOOLEAN, new Boolean(true)));

     layoutProperties.add(new Tunable("selected_only", "Only layout selected nodes",
                          Tunable.BOOLEAN, new Boolean(false)));

     layoutProperties.add(new Tunable("force_alg_settings", "Algorithm settings",
                          Tunable.GROUP, new Integer(5), new Boolean(true), null, Tunable.COLLAPSABLE));

     layoutProperties.add(new Tunable("defaultSpringCoefficient", "Default Spring Coefficient",
                          Tunable.DOUBLE, new Double(defaultSpringCoefficient)));

     layoutProperties.add(new Tunable("defaultSpringLength", "Default Spring Length",
                          Tunable.DOUBLE, new Double(defaultSpringLength)));

     layoutProperties.add(new Tunable("defaultNodeMass", "Default Node Mass",
                          Tunable.DOUBLE, new Double(defaultNodeMass)));

     layoutProperties.add(new Tunable("numIterations", "Number of Iterations",
                          Tunable.INTEGER, new Integer(numIterations)));

     layoutProperties.add(new Tunable("integrator", "Integration algorithm to use",
                          Tunable.LIST, new Integer(0),
                          (Object) integratorArray, (Object) null, 0));

 

The values are read in an update method:

  Tunable t = layoutProperties.get("selected_only");
  if ((t != null) && (t.valueChanged() || force))
    selectedOnly = ((Boolean) t.getValue()).booleanValue();

  t = layoutProperties.get("partition");
  if ((t != null) && (t.valueChanged() || force))
       setPartition(t.getValue().toString());

  t = layoutProperties.get("defaultSpringCoefficient");
  if ((t != null) && (t.valueChanged() || force))
    defaultSpringCoefficient = ((Double) t.getValue()).doubleValue();

  t = layoutProperties.get("defaultSpringLength");
  if ((t != null) && (t.valueChanged() || force))
    defaultSpringLength = ((Double) t.getValue()).doubleValue();

  t = layoutProperties.get("defaultNodeMass");
  if ((t != null) && (t.valueChanged() || force))
    defaultNodeMass = ((Double) t.getValue()).doubleValue();

  t = layoutProperties.get("numIterations");
  if ((t != null) && (t.valueChanged() || force))
    numIterations = ((Integer) t.getValue()).intValue();

  t = layoutProperties.get("integrator");
  if ((t != null) && (t.valueChanged() || force)) {
    if (((Integer) t.getValue()).intValue() == 0)
      integrator = new RungeKuttaIntegrator();
    else if (((Integer) t.getValue()).intValue() == 1)
      integrator = new EulerIntegrator();
    else
      return;
  }
 

LayoutProperties has a method LayoutProperties.getTunablePanel() that can be called to return a JPanel that contains all of the Tunable panels. These are combined into a dialog to allow users to set and update the values. By using addTunableValueListener(cytoscape.layout.TunableListener) a caller can be notified when a user changes a value.

Field Summary

static int	BOOLEAN Tunables of type BOOLEAN allow data entry of a boolean value: this is presented to the user as a simple check box.
static int	BUTTON The BUTTON Tunable provides a simple button to be presented to the user: the caller can provide an ActionListener to be called when the button is selected.
static int	COLLAPSABLE If the COLLAPSABLE flag is set for a GROUP Tunable, then this Group of Tunables should be collapsable, and will be rendered with a button to allow collapse/expand.
static int	DOUBLE Tunables of type DOUBLE allow data entry of double values, possibly bounded between lowerBound and upperBound: if the flag USESLIDER is set, and the caller provides both lower and upper bounds, the user is presented with a slider interface.
static int	EDGEATTRIBUTE Tunables of type EDGEATTRIBUTE present a user with a list of the currently defined edge attributes for selection: if the flag NUMERICATTRIBUTE is set, only integer or double attributes are shown, and if the MULTISELECT flag is set, the user is presented with a list from which multiple values can be selected, otherwise, the user is presented with a combo box.
static int	GROUP The GROUP Tunable provides a mechanism to improve the asthetics of the interface: the value of the GROUP Tunable indicates the number of the subsequent tunables that should be grouped together.
static int	IMMUTABLE If the IMMUTABLE flag is set, then the Tunable is presented as usual, with both label and user widget, but the user widget is disabled.
static int	INTEGER Tunables of type INTEGER allow data entry of integer values, possibly bounded between lowerBound and upperBound: if the flag USESLIDER is set, and the caller provides both lower and upper bounds, the user is presented with a slider interface.
static int	LIST Tunables of type LIST present a user with a list of values to select from: if the MULTISELECT flag is set, the user is presented with a list from which multiple values can be selected, otherwise, the user is presented with a combo box.
static int	MULTISELECT For LIST, NODEATTRIBUTE, or EDGEATTRIBUTE types, use a list widget that supports multiselect rather than a combo box.
static int	NODEATTRIBUTE Tunables of type NODEATTRIBUTE present a user with a list of the currently defined node attributes for selection: if the flag NUMERICATTRIBUTE is set, only integer or double attributes are shown, and if the MULTISELECT flag is set, the user is presented with a list from which multiple values can be selected, otherwise, the user is presented with a combo box.
static int	NOINPUT When the NOINPUT flag is set, this Tunable is not presented to the user, it is only used for property settings.
static int	NUMERICATTRIBUTE For attributes, indicate that the list should be restricted to integer or float attributes.
static int	STRING Tunables of type STRING allow data entry of text.
static int	USESLIDER For INTEGER or DOUBLE tunables, preferentially use a slider widget -- this will *only* take effect if the upper and lower bounds are provided.

Constructor Summary

Tunable(String name, String desc, int type, Object value)
Constructor to create a Tunable with no bounds information, and no flag.

Tunable(String name, String desc, int type, Object value, int flag)
Constructor to create a Tunable with no bounds information, but with a flag.

Tunable(String name, String desc, int type, Object value, Object lowerBound, Object upperBound, int flag)
Constructor to create a Tunable with bounds information as well as a flag.

Tunable(String name, String desc, int type, Object value, Object lowerBound, Object upperBound, int flag, boolean immutable)
Deprecated. Use the IMMUTABLE flag directly rather than this special constructor.

Method Summary

void	actionPerformed(ActionEvent e) This method is public as a byproduct of the implementation.
void	addTunableValueListener(TunableListener listener) Method to add a value listener to this Tunable.
boolean	checkFlag(int flag) This method is used to check the value of a flag.
void	clearFlag(int flag) This method can be used to clear a flag for this Tunable
void	focusGained(FocusEvent ev) This method is public as a byproduct of the implementation.
void	focusLost(FocusEvent ev) Document listener routines to handle bounds checking
String	getDescription() Method to return the description for this Tunable.
Object	getLowerBound() Method to get the lowerBound for this Tunable.
String	getName() Method to return a string representation of this Tunable, which is essentially its name.
JPanel	getPanel() This method returns a JPanel suitable for inclusion in the LayoutSettingsDialog to represent this Tunable.
int	getType() Method to return the type of this Tunable.
Object	getUpperBound() Method to get the upperBound for this Tunable.
Object	getValue() This method returns the current value.
void	itemStateChanged(ItemEvent e) This method is public as a byproduct of the implementation.
void	removeTunableValueListener(TunableListener listener) Method to remove a value listener from this Tunable.
void	setFlag(int flag) This method can be used to set a flag for this Tunable
void	setImmutable(boolean immutable) This method can be used to set the "immutable" boolean, which essentially get's mapped to the appropriate mechanism for allowing a value to be editted.
void	setLowerBound(Object lowerBound) Method to set the lowerBound for this Tunable.
void	setUpperBound(Object upperBound) Method to set the upperBound for this Tunable.
void	setValue(Object value) This method is used to set the value for this Tunable.
void	stateChanged(ChangeEvent e) This method is public as a byproduct of the implementation.
String	toString() Method to return a string representation of this Tunable, which is essentially its name.
void	updateValue() This method is called to extract the user-entered data from the JPanel and store it as our value.
void	updateValueListeners() Method to call all of the value listeners.
boolean	valueChanged() Returns the changed state of the value.
void	valueChanged(ListSelectionEvent e) This method is public as a byproduct of the implementation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

INTEGER

public static final int INTEGER

Tunables of type INTEGER allow data entry of integer values, possibly bounded between lowerBound and upperBound: if the flag USESLIDER is set, and the caller provides both lower and upper bounds, the user is presented with a slider interface.

See Also:

Constant Field Values

DOUBLE

public static final int DOUBLE

Tunables of type DOUBLE allow data entry of double values, possibly bounded between lowerBound and upperBound: if the flag USESLIDER is set, and the caller provides both lower and upper bounds, the user is presented with a slider interface.

See Also:

Constant Field Values

BOOLEAN

public static final int BOOLEAN

Tunables of type BOOLEAN allow data entry of a boolean value: this is presented to the user as a simple check box.

See Also:

Constant Field Values

STRING

public static final int STRING

Tunables of type STRING allow data entry of text.

See Also:

Constant Field Values

NODEATTRIBUTE

public static final int NODEATTRIBUTE

Tunables of type NODEATTRIBUTE present a user with a list of the currently defined node attributes for selection: if the flag NUMERICATTRIBUTE is set, only integer or double attributes are shown, and if the MULTISELECT flag is set, the user is presented with a list from which multiple values can be selected, otherwise, the user is presented with a combo box.

See Also:

Constant Field Values

EDGEATTRIBUTE

public static final int EDGEATTRIBUTE

Tunables of type EDGEATTRIBUTE present a user with a list of the currently defined edge attributes for selection: if the flag NUMERICATTRIBUTE is set, only integer or double attributes are shown, and if the MULTISELECT flag is set, the user is presented with a list from which multiple values can be selected, otherwise, the user is presented with a combo box.

See Also:

Constant Field Values

LIST

public static final int LIST

Tunables of type LIST present a user with a list of values to select from: if the MULTISELECT flag is set, the user is presented with a list from which multiple values can be selected, otherwise, the user is presented with a combo box.

See Also:

Constant Field Values

GROUP

public static final int GROUP

The GROUP Tunable provides a mechanism to improve the asthetics of the interface: the value of the GROUP Tunable indicates the number of the subsequent tunables that should be grouped together.

See Also:

Constant Field Values

BUTTON

public static final int BUTTON

The BUTTON Tunable provides a simple button to be presented to the user: the caller can provide an ActionListener to be called when the button is selected.

See Also:

Constant Field Values

NOINPUT

public static final int NOINPUT

When the NOINPUT flag is set, this Tunable is not presented to the user, it is only used for property settings.

See Also:

Constant Field Values

NUMERICATTRIBUTE

public static final int NUMERICATTRIBUTE

For attributes, indicate that the list should be restricted to integer or float attributes.

See Also:

Constant Field Values

MULTISELECT

public static final int MULTISELECT

For LIST, NODEATTRIBUTE, or EDGEATTRIBUTE types, use a list widget that supports multiselect rather than a combo box.

See Also:

Constant Field Values

USESLIDER

public static final int USESLIDER

For INTEGER or DOUBLE tunables, preferentially use a slider widget -- this will *only* take effect if the upper and lower bounds are provided.

See Also:

Constant Field Values

IMMUTABLE

public static final int IMMUTABLE

If the IMMUTABLE flag is set, then the Tunable is presented as usual, with both label and user widget, but the user widget is disabled.

See Also:

Constant Field Values

COLLAPSABLE

public static final int COLLAPSABLE

If the COLLAPSABLE flag is set for a GROUP Tunable, then this Group of Tunables should be collapsable, and will be rendered with a button to allow collapse/expand.

See Also:

Constant Field Values

Constructor Detail

Tunable

public Tunable(String name,
               String desc,
               int type,
               Object value)

Constructor to create a Tunable with no bounds information, and no flag.

Parameters:

name - The name of the Tunable

desc - The description of the Tunable

type - Integer value that represents the type of the Tunable. The type not only impact the way that the value is interpreted, but also the component used for the LayoutSettingsDialog

value - The initial (default) value of the Tunable

Tunable

public Tunable(String name,
               String desc,
               int type,
               Object value,
               int flag)

Constructor to create a Tunable with no bounds information, but with a flag.

Parameters:

name - The name of the Tunable

desc - The description of the Tunable

type - Integer value that represents the type of the Tunable. The type not only impact the way that the value is interpreted, but also the component used for the LayoutSettingsDialog

value - The initial (default) value of the Tunable

flag - The initial value of the flag. This can be used to indicate that this tunable is not user changeable (e.g. debug), or to indicate if there is a specific type for the attributes.

Tunable

public Tunable(String name,
               String desc,
               int type,
               Object value,
               Object lowerBound,
               Object upperBound,
               int flag)

Constructor to create a Tunable with bounds information as well as a flag.

Parameters:

name - The name of the Tunable

desc - The description of the Tunable

type - Integer value that represents the type of the Tunable. The type not only impact the way that the value is interpreted, but also the component used for the LayoutSettingsDialog

value - The initial (default) value of the Tunable. This is a String in the case of an EDGEATTRIBUTE or NODEATTRIBUTE tunable, it is an Integer index a LIST tunable.

lowerBound - An Object that either represents the lower bounds of a numeric Tunable or an array of values for an attribute (or other type of) list.

upperBound - An Object that represents the upper bounds of a numeric Tunable.

flag - The initial value of the flag. This can be used to indicate that this tunable is not user changeable (e.g. debug), or to indicate if there is a specific type for the attributes.

Tunable

public Tunable(String name,
               String desc,
               int type,
               Object value,
               Object lowerBound,
               Object upperBound,
               int flag,
               boolean immutable)

Deprecated. Use the IMMUTABLE flag directly rather than this special constructor.

Constructor to create a Tunable with bounds information as well as a flag.

Parameters:

name - The name of the Tunable

desc - The description of the Tunable

type - Integer value that represents the type of the Tunable. The type not only impact the way that the value is interpreted, but also the component used for the LayoutSettingsDialog

value - The initial (default) value of the Tunable. This is a String in the case of an EDGEATTRIBUTE or NODEATTRIBUTE tunable, it is an Integer index a LIST tunable.

lowerBound - An Object that either represents the lower bounds of a numeric Tunable or an array of values for an attribute (or other type of) list.

upperBound - An Object that represents the upper bounds of a numeric Tunable.

flag - The initial value of the flag. This can be used to indicate that this tunable is not user changeable (e.g. debug), or to indicate if there is a specific type for the attributes.

immutable - If 'true', this Tunable is immutable

Method Detail

setFlag

public void setFlag(int flag)

This method can be used to set a flag for this Tunable

Parameters:

flag - integer value the contains the flag to set.

clearFlag

public void clearFlag(int flag)

This method can be used to clear a flag for this Tunable

Parameters:

flag - integer value the contains the flag to be cleared.

checkFlag

public boolean checkFlag(int flag)

This method is used to check the value of a flag. It returns true if the flag is set, false otherwise.

Parameters:

flag - integer value the contains the flag to be checked.

Returns:

true if the flag is set.

setImmutable

public void setImmutable(boolean immutable)

This method can be used to set the "immutable" boolean, which essentially get's mapped to the appropriate mechanism for allowing a value to be editted.

Parameters:

immutable - 'true' if this is an immutable value

setValue

public void setValue(Object value)

This method is used to set the value for this Tunable. If this is an INTEGER, DOUBLE, or BOOLEAN Tunable, then value is assumed to be a String. This also sets the "changed" state of the value to "true".

Parameters:

value - Object (usually String) containing the value to be set

getValue

public Object getValue()

This method returns the current value. This method also resets the state of the value to indicate that it has not been changed since the last "get".

Returns:

Object that contains the value for this Tunable

valueChanged

public boolean valueChanged()

Returns the changed state of the value. If true, the value has been changed since it was last retrieved.

Returns:

boolean value of the changed state.

setLowerBound

public void setLowerBound(Object lowerBound)

Method to set the lowerBound for this Tunable. This might be used to change a Tunable based on changes in the plugin environment.

Parameters:

lowerBound - the new lowerBound for the tunable

getLowerBound

public Object getLowerBound()

Method to get the lowerBound for this Tunable.

Returns:

the lowerBound the tunable

setUpperBound

public void setUpperBound(Object upperBound)

Method to set the upperBound for this Tunable. This might be used to change a Tunable based on changes in the plugin environment.

Parameters:

upperBound - the new upperBound for the tunable

getUpperBound

public Object getUpperBound()

Method to get the upperBound for this Tunable.

Returns:

the upperBound the tunable

toString

public String toString()

Method to return a string representation of this Tunable, which is essentially its name.

Overrides:

toString in class Object

Returns:

String value of the name of the Tunable.

getName

public String getName()

Method to return a string representation of this Tunable, which is essentially its name.

Returns:

String value of the name of the Tunable.

getType

public int getType()

Method to return the type of this Tunable.

Returns:

Tunable type

getDescription

public String getDescription()

Method to return the description for this Tunable.

Returns:

Tunable description

addTunableValueListener

public void addTunableValueListener(TunableListener listener)

Method to add a value listener to this Tunable. A value listener is called whenever a tunable value is updated by the user (as opposed to programmatically). This can be used to change the UI based on certain inputs.

Parameters:

listener - the TunableListener to add

removeTunableValueListener

public void removeTunableValueListener(TunableListener listener)

Method to remove a value listener from this Tunable. A value listener is called whenever a tunable value is updated by the user (as opposed to programmatically). This can be used to change the UI based on certain inputs.

Parameters:

listener - the TunableListener to remove

updateValueListeners

public void updateValueListeners()

Method to call all of the value listeners.

getPanel

public JPanel getPanel()

This method returns a JPanel suitable for inclusion in the LayoutSettingsDialog to represent this Tunable. Note that while the type of the widgets used to represent the Tunable are customized to represent the type, no ActionListeners are included. The dialog must call updateSettings to set the value of the Tunable from the user input data.

Returns:

JPanel that can be used to enter values for this Tunable

updateValue

public void updateValue()

This method is called to extract the user-entered data from the JPanel and store it as our value.

focusLost

public void focusLost(FocusEvent ev)

Document listener routines to handle bounds checking

Specified by:

focusLost in interface FocusListener

focusGained

public void focusGained(FocusEvent ev)

This method is public as a byproduct of the implementation.

Specified by:

focusGained in interface FocusListener

stateChanged

public void stateChanged(ChangeEvent e)

This method is public as a byproduct of the implementation.

Specified by:

stateChanged in interface ChangeListener

actionPerformed

public void actionPerformed(ActionEvent e)

This method is public as a byproduct of the implementation.

Specified by:

actionPerformed in interface ActionListener

itemStateChanged

public void itemStateChanged(ItemEvent e)

This method is public as a byproduct of the implementation.

Specified by:

itemStateChanged in interface ItemListener

valueChanged

public void valueChanged(ListSelectionEvent e)

This method is public as a byproduct of the implementation.

Specified by:

valueChanged in interface ListSelectionListener