prefuse.action.assignment
Class DataSizeAction

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