org.rosuda.ibase.toolkit
Class Axis

java.lang.Object
  org.rosuda.ibase.Notifier
      org.rosuda.ibase.toolkit.Axis

public class Axis
extends Notifier

Axis - implements transformation of cases, values or categories to orthogonal graphical coordinates and vice versa. Supported axis types are: numerical, equidistant (i.e. nominal/ordinal by index), categorical-equidistant, categorical-proportional by population.

Version:

$Id: Axis.java 2662 2006-10-25 16:41:55Z urbaneks $

Field Summary

int	datacount count for discrete axes
boolean	drawAxis
int	gBegin graphical start and length
int	gLen graphical start and length
static int	O_Horiz Axis orientation: horizontal (X)
static int	O_Vert Axis orientation: vertical (Y)
static int	O_X Axis orientation: horizontal (X)
static int	O_Y Axis orientation: vertical (Y)
static int	T_EqCat Axis type: equidistant categorical
static int	T_EqSize Axis type: equidistant (i.e. discrete/nominal/ordinal by index)
static int	T_Num Axis type: numerical
static int	T_PropCat Axis type: proportional categorical
int	trl orthogonal translation in percent
double	vBegin value begin and length
double	vLen value begin and length

Constructor Summary

Axis(SVar srcv)
create a new Axis with variable srcv, default orientation (horizontal) and default type guessing and default range

Axis(SVar srcv, int orientation, int axisType)
create new Axis with variable srvc, specified orientation and type and default range

Method Summary

int	clip(int gv) clips supplied graphical value to axis' region
int	getCasePos(int i) get graphical position of case with index i (for categorial vars returns the same as getCatCenter called for the category of the case)
int	getCatAtSeqIndex(int c) Inverse of getCatSeqIndex(int).
int	getCatByPos(int pos) get category corresponding to a position on screen (type1 and 2 only)
int	getCatCenter(int i) get central geometry for category of index i (just a faster way to get (Low+Up)/2 )
int	getCatLow(int i) get lower geometry for category of index i (type 1,2 only)
int	getCatSeqIndex(int c) for cat types return the position of a category in the sequence of categories. w/o reordering it's always c.
int	getCatUp(int i) get upper geometry for category of index i (type 1,2 only)
java.lang.String	getDisplayableValue(double val) returns string representation of the supplied value, taking into account the range (vLen) to determine how many digits to display behind the fp
int	getOrientation() return axis orientation
int	getRegularCatPos(int i, int leftGap, int rightGap) get regular geometry for category of index i (e.g. for parallel coordinates plots)
double	getSensibleTickDistance(int medDist, int minDist) returns a tick distance that is somewhat "sensible" to be used for ticks given mean required distance.
double	getSensibleTickStart(double tickDist) returns first visible tick given a tick distance. it is mostly used in conjunction with getSensibleTickDistance(int, int)
int	getType()
double	getValueForPos(int pos) get value corresponding to a geometrical position val (for type=0 and 3 only), hence this is the inverse of getValuePos(double)
int	getValuePos(double val) get graphical position of value val (for type=0 and 3 only)
double[]	getValueRange() returns value range as an array of two doubles specifying top and bottom end. to ensure reproducibility the orientation is preserved, therefore it is not guaranteed that the second value is greater that the first one.
SVar	getVariable() returns associated variable.
boolean	moveCat(int c, int npos) move category to another position in the sequence, all remaining categories between the current and new position will be moved correspondingly
void	setDefaultRange() set default range for the axis (ie for numerical variable min, max are used, for all other types the maixmal count is used.
void	setDefaultRange(boolean resetCseq) set default range for the axis (i.e. for numerical variable min, max are used, for all other types the maixmal count is used.)
void	setGeometry(int orientation, int begin, int len) set geomery of the axis and notifies dependents upon change
void	setOrthTrans(int trl) moves the axis along the orthogonal direction
void	setType(int nt) change axis type (implicitely calls setDefaultRange() but preserves cat sequence if switching between "compatible" types, i.e. 1 and 2)
boolean	setValueRange(double[] range) same as setValueRange(double, double), but takes an array of two doubles as returned by getValueRange()
boolean	setValueRange(double begin, double len) for numerical variables - set range of the variable's values.
boolean	setValueRange(int dc) for discrete axis types - set the data count
void	setVariable(SVar var)
boolean	swapCats(int c1, int c2) swap positions of two categories
java.lang.String	toString() somewhat simple toString implementation, basically for debugging purposes

Methods inherited from class org.rosuda.ibase.Notifier

addDepend, beginBatch, delDepend, endBatch, NotifyAll, NotifyAll, NotifyAll, NotifyAll, startCascadedNotifyAll

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

O_Horiz

public static final int O_Horiz

Axis orientation: horizontal (X)

See Also:

Constant Field Values

O_Vert

public static final int O_Vert

Axis orientation: vertical (Y)

See Also:

Constant Field Values

O_X

public static final int O_X

Axis orientation: horizontal (X)

See Also:

Constant Field Values

O_Y

public static final int O_Y

Axis orientation: vertical (Y)

See Also:

Constant Field Values

T_Num

public static final int T_Num

Axis type: numerical

See Also:

Constant Field Values

T_EqCat

public static final int T_EqCat

Axis type: equidistant categorical

See Also:

Constant Field Values

T_PropCat

public static final int T_PropCat

Axis type: proportional categorical

See Also:

Constant Field Values

T_EqSize

public static final int T_EqSize

Axis type: equidistant (i.e. discrete/nominal/ordinal by index)

See Also:

Constant Field Values

gBegin

public int gBegin

graphical start and length

gLen

public int gLen

graphical start and length

vBegin

public double vBegin

value begin and length

vLen

public double vLen

value begin and length

datacount

public int datacount

count for discrete axes

trl

public int trl

orthogonal translation in percent

drawAxis

public boolean drawAxis

Constructor Detail

Axis

public Axis(SVar srcv)

create a new Axis with variable srcv, default orientation (horizontal) and default type guessing and default range

Parameters:

srcv - source variable (cannot be null! for pure numerical axes use constructor!)

Axis

public Axis(SVar srcv,
            int orientation,
            int axisType)

create new Axis with variable srvc, specified orientation and type and default range

Parameters:

srcv - source variable (can be null if axis type is T_Num or T_EqSize resulting in virtual axis)

orientation - orientation

axisType - axis type

Method Detail

getOrientation

public int getOrientation()

return axis orientation

Returns:

axis orientation

setType

public void setType(int nt)

change axis type (implicitely calls setDefaultRange() but preserves cat sequence if switching between "compatible" types, i.e. 1 and 2)

getType

public int getType()

setGeometry

public void setGeometry(int orientation,
                        int begin,
                        int len)

set geomery of the axis and notifies dependents upon change

Parameters:

orientation - orientation of the axis (horiz/vert)

begin - begin/anchor of the axis - i.e. the pixel to correspond to vBegin

length - length of the axis (note: may be negative if necessary)

setValueRange

public boolean setValueRange(double begin,
                             double len)

for numerical variables - set range of the variable's values.

Parameters:

begin - begin/anchor of axis in data domain

len - length of the axis (can be negative if necessary)

Returns:

true if this method had any effect on the Axis or false if the values match status quo

setValueRange

public boolean setValueRange(double[] range)

same as setValueRange(double, double), but takes an array of two doubles as returned by getValueRange()

setValueRange

public boolean setValueRange(int dc)

for discrete axis types - set the data count

Parameters:

dc - data count, if <1 then set to 1

Returns:

true if this method had any effect on the Axis or false if the values match status quo

setDefaultRange

public void setDefaultRange()

set default range for the axis (ie for numerical variable min, max are used, for all other types the maixmal count is used. For categorial types this also resets categories sequence to default (ordered by cat ID) - equals to calling @link{#setDefaultRange(boolean) setDefaultRange(true)}

setDefaultRange

public void setDefaultRange(boolean resetCseq)

set default range for the axis (i.e. for numerical variable min, max are used, for all other types the maixmal count is used.)

Parameters:

reseCseq - If true for categorial types this also resets categories sequence to default (ordered by cat ID)

getVariable

public SVar getVariable()

returns associated variable. Please note that this can be null for virtual axes

setVariable

public void setVariable(SVar var)

getCasePos

public int getCasePos(int i)

get graphical position of case with index i (for categorial vars returns the same as getCatCenter called for the category of the case)

Parameters:

i - index of the case

Returns:

graphical position of the case

getValuePos

public int getValuePos(double val)

get graphical position of value val (for type=0 and 3 only)

Parameters:

val - value

Returns:

graphical position of the value

getValueForPos

public double getValueForPos(int pos)

get value corresponding to a geometrical position val (for type=0 and 3 only), hence this is the inverse of getValuePos(double)

Parameters:

pos - position on the screen

Returns:

value corresponding to the supplied position

clip

public int clip(int gv)

clips supplied graphical value to axis' region

Parameters:

gv - graphical value

Returns:

clipped graphical value

getCatLow

public int getCatLow(int i)

get lower geometry for category of index i (type 1,2 only)

Parameters:

i - category index

Returns:

lower position of the category

getCatUp

public int getCatUp(int i)

get upper geometry for category of index i (type 1,2 only)

Parameters:

i - category index

Returns:

upper position of the category

getCatCenter

public int getCatCenter(int i)

get central geometry for category of index i (just a faster way to get (Low+Up)/2 )

Parameters:

i - category index

Returns:

central position of the category

getRegularCatPos

public int getRegularCatPos(int i,
                            int leftGap,
                            int rightGap)

get regular geometry for category of index i (e.g. for parallel coordinates plots)

Parameters:

i - category index

leftGap - left gap

rightGap - right gap

Returns:

regular position of the category

getCatByPos

public int getCatByPos(int pos)

get category corresponding to a position on screen (type1 and 2 only)

Parameters:

pos - position

Returns:

category ID or -1 on failure (e.g. if not of type 1 or 2)

swapCats

public boolean swapCats(int c1,
                        int c2)

swap positions of two categories

Parameters:

c1 - category 1

c2 - category 2

Returns:

true on success, false on failure (i.e. some index was out of bounds)

moveCat

public boolean moveCat(int c,
                       int npos)

move category to another position in the sequence, all remaining categories between the current and new position will be moved correspondingly

Parameters:

c - category to move

npos - new position in the sequence - it is clipped if necessary, i.e. specifying values <0 will move it to the begining and >=cats will move it to the end of the sequence

Returns:

true on success, false on failure

getCatSeqIndex

public int getCatSeqIndex(int c)

for cat types return the position of a category in the sequence of categories. w/o reordering it's always c. It is often used in conjunction with moveCat(int, int) as npos parameter when destination is also a category

Parameters:

c - category index

Returns:

position of the category in the sequence

getCatAtSeqIndex

public int getCatAtSeqIndex(int c)

Inverse of getCatSeqIndex(int).

getSensibleTickDistance

public double getSensibleTickDistance(int medDist,
                                      int minDist)

returns a tick distance that is somewhat "sensible" to be used for ticks given mean required distance. The tick distance will be a power of 10. The result can be used to obtain more sophisticated tick values by simply dividing by 2,4 or 5 - or alternatively multipl. by 2, 2.5 or 5

Parameters:

medDist - mean required distance

mindist - minimal required distance (if set to 0 only powers of 10 will be used)

Returns:

proposed tick distance

getSensibleTickStart

public double getSensibleTickStart(double tickDist)

returns first visible tick given a tick distance. it is mostly used in conjunction with getSensibleTickDistance(int, int)

Parameters:

tickDist - tick distance

Returns:

first visible tick mark

getDisplayableValue

public java.lang.String getDisplayableValue(double val)

returns string representation of the supplied value, taking into account the range (vLen) to determine how many digits to display behind the fp

Parameters:

val - value to display

Returns:

string representation of the value

getValueRange

public double[] getValueRange()

returns value range as an array of two doubles specifying top and bottom end. to ensure reproducibility the orientation is preserved, therefore it is not guaranteed that the second value is greater that the first one.

setOrthTrans

public void setOrthTrans(int trl)

moves the axis along the orthogonal direction

toString

public java.lang.String toString()

somewhat simple toString implementation, basically for debugging purposes

Overrides:

toString in class java.lang.Object