prefuse.action.assignment
Class DataSizeAction

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.SizeAction
                          extended by prefuse.action.assignment.DataSizeAction

public class DataSizeAction
extends SizeAction

Assignment Action that assigns size values for a group of items based upon a data field. This action can be used to automatically vary item's on screen sizes proportionally to an underlying data value. Sizes can be assigned along a continuous scale, or can be binned into discrete size groups. Both 1D (length) and 2D (area) encodings are supported by this function. 2D is assumed by default; use the setIs2DArea method to change this.

The size assignments for numerical data are continuous by default, but can be binned into a few discrete steps (see setBinCount(int)). Quantitative data can also be sized 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.

By default, the maximum size value is determined automatically from the data, faithfully representing the scale differences between data values. However, this can sometimes result in very large differences. For example, if the minimum data value is 1.0 and the largest is 200.0, the largest items will be 200 times larger than the smallest. While accurate, this may not result in the most readable display. To correct these cases, use the setMaximumSize(double) method to manually set the range of allowed sizes. By default, the minimum size value is 1.0. This too can be changed using the setMinimumSize(double) method.

Author:
jeffrey heer

Field Summary
protected  int m_bins
           
protected  java.lang.String m_dataField
           
protected  double[] m_dist
           
protected  boolean m_inferBounds
           
protected  boolean m_inferRange
           
protected  boolean m_is2DArea
           
protected  double m_minSize
           
protected  int m_scale
           
protected  double m_sizeRange
           
protected  int m_tempScale
           
protected static double NO_SIZE
           
 
Fields inherited from class prefuse.action.assignment.SizeAction
m_defaultSize
 
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
DataSizeAction(java.lang.String group, java.lang.String field)
          Create a new DataSizeAction.
DataSizeAction(java.lang.String group, java.lang.String field, int bins)
          Create a new DataSizeAction.
DataSizeAction(java.lang.String group, java.lang.String field, int bins, int scale)
          Create a new DataSizeAction.
 
Method Summary
protected  void finish()
          Perform any necessary clean-up after this encoder can be used.
 int getBinCount()
          Returns the number of "bins" or distinct categories of sizes
 java.lang.String getDataField()
          Returns the data field used to encode size values.
 double getMaximumSize()
          Gets the maximum size value that will be assigned by this action.
 double getMinimumSize()
          Gets the size assigned to the lowest-valued data items, typically 1.0.
 int getScale()
          Returns the scale type used for encoding size values from the data.
 double getSize(VisualItem item)
          Returns a size value for the given item.
 boolean is2DArea()
          Indicates if the size values set by this function represent 2D areas.
 void setBinCount(int count)
          Sets the number of "bins" or distinct categories of sizes
 void setDataField(java.lang.String field)
          Set the data field used to encode size values.
 void setDefaultSize(double defaultSize)
          This operation is not supported by the DataSizeAction type.
 void setIs2DArea(boolean isArea)
          Sets if the size values set by this function represent 2D areas.
 void setMaximumSize(double maxSize)
          Set the maximum size value that will be assigned by this action.
 void setMinimumSize(double size)
          Sets the size assigned to the lowest-valued data items.
 void setScale(int scale)
          Set the scale (linear, square root, or log) to use for encoding size values from the data.
protected  void setup()
          Perform any necessary setup before this encoder can be used.
 
Methods inherited from class prefuse.action.assignment.SizeAction
add, add, add, add, getDefaultSize, process
 
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
 

Field Detail

NO_SIZE

protected static final double NO_SIZE
See Also:
Constant Field Values

m_dataField

protected java.lang.String m_dataField

m_minSize

protected double m_minSize

m_sizeRange

protected double m_sizeRange

m_scale

protected int m_scale

m_bins

protected int m_bins

m_inferBounds

protected boolean m_inferBounds

m_inferRange

protected boolean m_inferRange

m_is2DArea

protected boolean m_is2DArea

m_dist

protected double[] m_dist

m_tempScale

protected int m_tempScale
Constructor Detail

DataSizeAction

public DataSizeAction(java.lang.String group,
                      java.lang.String field)
Create a new DataSizeAction.

Parameters:
group - the data group to process
field - the data field to base size assignments on

DataSizeAction

public DataSizeAction(java.lang.String group,
                      java.lang.String field,
                      int bins)
Create a new DataSizeAction.

Parameters:
group - the data group to process
field - the data field to base size assignments on
bins - the number of discrete size values to use

DataSizeAction

public DataSizeAction(java.lang.String group,
                      java.lang.String field,
                      int bins,
                      int scale)
Create a new DataSizeAction.

Parameters:
group - the data group to process
field - the data field to base size assignments on
bins - the number of discrete size values to use
scale - the scale type to use. One of Constants.LINEAR_SCALE, Constants.LOG_SCALE, Constants.SQRT_SCALE, or Constants.QUANTILE_SCALE. If a quantile scale is used, the number of bins must be greater than zero.
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

getScale

public int getScale()
Returns the scale type used for encoding size values from the 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 size values from the 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 distinct categories of sizes

Returns:
the number of bins.

setBinCount

public void setBinCount(int count)
Sets the number of "bins" or distinct categories of sizes

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.

is2DArea

public boolean is2DArea()
Indicates if the size values set by this function represent 2D areas. That is, if the size is a 2D area or a 1D length. The size value will be scaled appropriately to facilitate better perception of size differences.

Returns:
true if this instance is configured for area sizes, false for length sizes.
See Also:
PrefuseLib.getSize2D(double)

setIs2DArea

public void setIs2DArea(boolean isArea)
Sets if the size values set by this function represent 2D areas. That is, if the size is a 2D area or a 1D length. The size value will be scaled appropriately to facilitate better perception of size differences.

Parameters:
isArea - true to configure this instance for area sizes, false for length sizes
See Also:
PrefuseLib.getSize2D(double)

getMinimumSize

public double getMinimumSize()
Gets the size assigned to the lowest-valued data items, typically 1.0.

Returns:
the size for the lowest-valued data items

setMinimumSize

public void setMinimumSize(double size)
Sets the size assigned to the lowest-valued data items. By default, this value is 1.0.

Parameters:
size - the new size for the lowest-valued data items

getMaximumSize

public double getMaximumSize()
Gets the maximum size value that will be assigned by this action. By default, the maximum size value is determined automatically from the data, faithfully representing the scale differences between data values. However, this can sometimes result in very large differences. For example, if the minimum data value is 1.0 and the largest is 200.0, the largest items will be 200 times larger than the smallest. While accurate, this may not result in the most readable display. To correct these cases, use the setMaximumSize(double) method to manually set the range of allowed sizes.

Returns:
the current maximum size. For the returned value to accurately reflect the size range used by this action, either the action must have already been run (allowing the value to be automatically computed) or the maximum size must have been explicitly set.

setMaximumSize

public void setMaximumSize(double maxSize)
Set the maximum size value that will be assigned by this action. By default, the maximum size value is determined automatically from the data, faithfully representing the scale differences between data values. However, this can sometimes result in very large differences. For example, if the minimum data value is 1.0 and the largest is 200.0, the largest items will be 200 times larger than the smallest. While accurate, this may not result in the most readable display. To correct these cases, use the setMaximumSize(double) method to manually set the range of allowed sizes.

Parameters:
maxSize - the maximum size to use. If this value is less than or equal to zero, infinite, or not a number (NaN) then the input value will be ignored and instead automatic inference of the size range will be performed.

setDefaultSize

public void setDefaultSize(double defaultSize)
This operation is not supported by the DataSizeAction type. Calling this method will result in a thrown exception.

Overrides:
setDefaultSize in class SizeAction
Parameters:
defaultSize - the new default size value
Throws:
java.lang.UnsupportedOperationException
See Also:
SizeAction.setDefaultSize(double)

setup

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

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
See Also:
EncoderAction.finish()

getSize

public double getSize(VisualItem item)
Description copied from class: SizeAction
Returns a size value for the given item.

Overrides:
getSize in class SizeAction
Parameters:
item - the item for which to get the size value
Returns:
the size value for the item
See Also:
SizeAction.getSize(prefuse.visual.VisualItem)


Copyright 2007 Regents of the University of California