prefuse.action.assignment
Class DataColorAction

java.lang.Object
  prefuse.activity.Activity
      prefuse.action.Action
          prefuse.action.GroupAction
              prefuse.action.ItemAction
                  prefuse.action.EncoderAction
                      prefuse.action.assignment.ColorAction
                          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)