Cytoscape 2.6.2 (c) 2006,2007 ISB, MSKCC, UCSD

cytoscape.layout
Class Tunable

java.lang.Object
  extended by 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:

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
equals, 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

www.cytoscape.org