prefuse.action.assignment
Class DataColorAction

java.lang.Object
  extended by prefuse.activity.Activity
      extended by prefuse.action.Action
          extended by prefuse.action.GroupAction
              extended by prefuse.action.ItemAction
                  extended by prefuse.action.EncoderAction
                      extended by prefuse.action.assignment.ColorAction
                          extended by prefuse.action.assignment.DataColorAction

public class DataColorAction
extends ColorAction

Assignment Action that assigns color values for a group of items based upon a data field. The type of color encoding used is dependent upon the reported data type. Nominal (categorical) data is encoded using a different hue for each unique data value. Ordinal (ordered) and Numerical (quantitative) data is shown using a grayscale color ramp. In all cases, the default color palette used by this Action can be replaced with a client-specified palette provided to the DataColorAction constructor.

The color spectra for numerical data is continuous by default, but can also be binned into a few discrete steps (see setBinCount(int)). Quantitative data can also be colored on different numerical scales. The default scale is a linear scale (specified by Constants.LINEAR_SCALE), but logarithmic and square root scales can be used (specified by Constants.LOG_SCALE and Constants.SQRT_SCALE respectively. Finally, the scale can be broken into quantiles, reflecting the statistical distribution of the values rather than just the total data value range, using the Constants.QUANTILE_SCALE value. For the quantile scale to work, you also need to specify the number of bins to use (see setBinCount(int)). This value will determine the number of quantiles that the data should be divided into.

Author:
jeffrey heer

Field Summary
 
Fields inherited from class prefuse.action.assignment.ColorAction
m_cidx, m_colorField, m_defaultColor, m_eidx, m_endField, m_sidx, m_startField
 
Fields inherited from class prefuse.action.ItemAction
m_predicate
 
Fields inherited from class prefuse.action.GroupAction
m_group
 
Fields inherited from class prefuse.action.Action
m_vis
 
Fields inherited from class prefuse.activity.Activity
DEFAULT_STEP_TIME, INFINITY
 
Constructor Summary
DataColorAction(java.lang.String group, java.lang.String dataField, int dataType, java.lang.String colorField)
          Create a new DataColorAction
DataColorAction(java.lang.String group, java.lang.String dataField, int dataType, java.lang.String colorField, int[] palette)
          Create a new DataColorAction
 
Method Summary
protected  int[] createPalette(int size)
          Create a color palette of the requested type and size.
protected  void finish()
          Perform any necessary clean-up after this encoder can be used.
 int getBinCount()
          Returns the number of "bins" or discrete steps of color.
 int getColor(VisualItem item)
          Returns a color value for the given item.
 java.lang.String getDataField()
          Returns the data field used to encode size values.
 int getDataType()
          Return the data type used by this action.
protected  double[] getDistribution()
          Computes the distribution (either min/max or quantile values) used to help assign colors to data values.
 int getScale()
          Returns the scale type used for encoding color values from the data.
 void setBinCount(int count)
          Sets the number of "bins" or or discrete steps of color.
 void setDataField(java.lang.String field)
          Set the data field used to encode size values.
 void setDataType(int type)
          Set the data type used by this action.
 void setDefaultColor(int color)
          This operation is not supported by the DataColorAction type.
 void setOrdinalMap(java.lang.Object[] values)
          Manually sets the ordered list of values to use for color assignment.
 void setScale(int scale)
          Set the scale (linear, square root, or log) to use for encoding color values from the data.
protected  void setup()
          Set up the state of this encoding Action.
 
Methods inherited from class prefuse.action.assignment.ColorAction
add, add, add, add, getDefaultColor, process, setField
 
Methods inherited from class prefuse.action.EncoderAction
add, clear, lookup, remove, run, setVisualization
 
Methods inherited from class prefuse.action.ItemAction
getFilterPredicate, setFilterPredicate
 
Methods inherited from class prefuse.action.GroupAction
getGroup, setGroup
 
Methods inherited from class prefuse.action.Action
getVisualization, run
 
Methods inherited from class prefuse.activity.Activity
addActivityListener, alwaysRunAfter, cancel, fireActivityCancelled, fireActivityFinished, fireActivityScheduled, fireActivityStarted, fireActivityStepped, getDuration, getNextTime, getPace, getPacingFunction, getStartTime, getStepTime, getStopTime, isEnabled, isRunning, isScheduled, removeActivityListener, run, runAfter, runAt, setDuration, setEnabled, setPacingFunction, setStartTime, setStepTime
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DataColorAction

public DataColorAction(java.lang.String group,
                       java.lang.String dataField,
                       int dataType,
                       java.lang.String colorField)
Create a new DataColorAction

Parameters:
group - the data group to process
dataField - the data field to base size assignments on
dataType - the data type to use for the data field. One of Constants.NOMINAL, Constants.ORDINAL, or Constants.NUMERICAL, for whether the data field represents categories, an ordered sequence, or numerical values.
colorField - the color field to assign

DataColorAction

public DataColorAction(java.lang.String group,
                       java.lang.String dataField,
                       int dataType,
                       java.lang.String colorField,
                       int[] palette)
Create a new DataColorAction

Parameters:
group - the data group to process
dataField - the data field to base size assignments on
dataType - the data type to use for the data field. One of Constants.NOMINAL, Constants.ORDINAL, or Constants.NUMERICAL, for whether the data field represents categories, an ordered sequence, or numerical values.
colorField - the color field to assign
palette - the color palette to use. See ColorLib for color palette generators.
Method Detail

getDataField

public java.lang.String getDataField()
Returns the data field used to encode size values.

Returns:
the data field that is mapped to size values

setDataField

public void setDataField(java.lang.String field)
Set the data field used to encode size values.

Parameters:
field - the data field to map to size values

getDataType

public int getDataType()
Return the data type used by this action. This value is one of Constants.NOMINAL, Constants.ORDINAL, or Constants.NUMERICAL.

Returns:
the data type used by this action

setDataType

public void setDataType(int type)
Set the data type used by this action.

Parameters:
type - the data type used by this action, one of Constants.NOMINAL, Constants.ORDINAL, or Constants.NUMERICAL.

getScale

public int getScale()
Returns the scale type used for encoding color values from the data. This value is only used for Constants.NUMERICAL data.

Returns:
the scale type. One of Constants.LINEAR_SCALE, Constants.LOG_SCALE, Constants.SQRT_SCALE, Constants.QUANTILE_SCALE.

setScale

public void setScale(int scale)
Set the scale (linear, square root, or log) to use for encoding color values from the data. This value is only used for Constants.NUMERICAL data.

Parameters:
scale - the scale type to use. This value should be one of Constants.LINEAR_SCALE, Constants.SQRT_SCALE, Constants.LOG_SCALE, Constants.QUANTILE_SCALE. If Constants.QUANTILE_SCALE is used, the number of bins to use must also be specified to a value greater than zero using the setBinCount(int) method.

getBinCount

public int getBinCount()
Returns the number of "bins" or discrete steps of color. This value is only used for numerical data.

Returns:
the number of bins.

setBinCount

public void setBinCount(int count)
Sets the number of "bins" or or discrete steps of color. This value is only used for numerical data.

Parameters:
count - the number of bins to set. The value Constants.CONTINUOUS indicates not to use any binning. If the scale type set using the setScale(int) method is Constants.QUANTILE_SCALE, the bin count must be greater than zero.

setDefaultColor

public void setDefaultColor(int color)
This operation is not supported by the DataColorAction type. Calling this method will result in a thrown exception.

Overrides:
setDefaultColor in class ColorAction
Parameters:
color - the new default color
Throws:
java.lang.UnsupportedOperationException
See Also:
ColorAction.setDefaultColor(int)

setOrdinalMap

public void setOrdinalMap(java.lang.Object[] values)
Manually sets the ordered list of values to use for color assignment. Normally, this ordering is computed using the methods of the DataLib class. This method allows you to set your own custom ordering. This ordering corresponds to the ordering of colors in this action's color palette. If the provided array of values is missing a value contained within the data, an exception will result during execution of this action.

Parameters:
values - the ordered list of values. If this array is missing a value contained within data processed by this action, an exception will be thrown when this action is run.

setup

protected void setup()
Set up the state of this encoding Action.

Overrides:
setup in class EncoderAction
See Also:
EncoderAction.setup()

finish

protected void finish()
Description copied from class: EncoderAction
Perform any necessary clean-up after this encoder can be used. By default does nothing. Subclasses can override this method to perform custom clean-up after the Action is used.

Overrides:
finish in class EncoderAction

getDistribution

protected double[] getDistribution()
Computes the distribution (either min/max or quantile values) used to help assign colors to data values.


createPalette

protected int[] createPalette(int size)
Create a color palette of the requested type and size.


getColor

public int getColor(VisualItem item)
Description copied from class: ColorAction
Returns a color value for the given item. Colors are represented as integers, interpreted as holding values for the red, green, blue, and alpha channels. This is the same color representation returned by the Color.getRGB() method.

Overrides:
getColor in class ColorAction
Parameters:
item - the item for which to get the color value
Returns:
the color value for the item
See Also:
ColorAction.getColor(prefuse.visual.VisualItem)


Copyright 2007 Regents of the University of California