mesquite.categ.lib
Class CategoricalState

java.lang.Object
  mesquite.lib.characters.CharacterState
      mesquite.categ.lib.CategoricalState

Direct Known Subclasses:

MolecularState

public class CategoricalState
extends CharacterState

This class provides some basic utilities for sets of states of categorical characters. Many of the utilities are static to be used for basic set calculations, but a categorical set can also be instantiated so as to have a parameter to pass by reference. In most calculates, state sets of categorical characters are NOT stored with these objects because it would be too costly. Instead, they are stored as simple long variables (64 bits, 56 possible states).

Field Summary

static long	dataBitsMask The mask that preserves bits 0..
static long	highBitsMask The mask that preserves the high bits used for special flags
static long	impossible The state (1L<<62) that corresponds to an invalid CategoricalState.
static long	inapplicable The state that corresponds to a gap (inapplicable)
static int	inapplicableBit The bit that signals a gap (inapplicable)
static int	inapplicableBitInt
static long	intStatesBitsMaskL
static int	lowerCaseBit The bit that signals the symbol is to be shown lower case
static int	maxCategoricalState The maximum allowed categorical state (55)
static int	polymorphismElement a value for arrays that store information about frequency of states; this would need to change if ever maxCategoricalState goes to 58
static long	shortStatesBitsMaskL The masks that preserves bits 0..
static long	statesBitsMask The mask that preserves bits 0..
static int	statesBitsMaskInt
static int	TOTALBITS
static long	unassigned The state (1L<<63) that corresponds to missing data.
static int	unassignedBit The bit that signals missing data
static int	unassignedBitInt Bits to be used if int used instead of long for state storage
static int	uncertainBit The bit that signals uncertainty
static int	uncertainBitInt

Constructor Summary

CategoricalState()

CategoricalState(long initial)

Method Summary

static long	addToSet(long s, int e) return the result of adding state e to state set s
int	cardinality() returns number of states in state set
static int	cardinality(int shortS) returns number of states in state set shortS
static int	cardinality(long s) returns number of states in state set s
static long	chooseHighest(double[] values, double toleranceProportion)
static long	chooseHighestWithinFactor(double[] values, double factor)
static long	chooseLowest(double[] values, double toleranceProportion)
static long	clearFromSet(long s, int e) return the result of subtracting state e to state set s
static long	clearFromSet(long s, long e) return the result of subtracting state e to state set s
static long	compressFromList(int[] states) Compresses array listing included elements into state set form (long, with bits set).
static long	compressFromPresence(double[] states) Compresses array with presence (>0) or absence (<=0) for each element into state set form (long, with bits set).
static boolean	compressibleToInt(long s)
static boolean	compressibleToShort(long s)
static int	compressToInt(long s)
static short	compressToShort(long s)
static long	emptySet() returns state set
boolean	equals(CharacterState s) returns true iff state sets are same
boolean	equals(CharacterState s, boolean allowMissing) returns true iff state sets are same
boolean	equals(CharacterState s, boolean allowMissing, boolean allowNearExact) returns true iff state sets are same
boolean	equals(CharacterState s, boolean allowMissing, boolean allowNearExact, boolean allowSubset) returns true iff state sets are same
static int[]	expand(long s) Expands state set (passed as long) to full array of included elements.
static long	expandFromInt(int s)
static long	expandFromShort(short s)
static long	firstSet(int numInSet) Returns the set that is {0,...,(numInSet-1)} That is, the first "numInSet" bits are set.
long	fromChar(char c) return the state set containing the state represented by the character (e.g., '0' to {0}); Used default symbols since no CharacterData is specified �
static long	fullSet() returns state set consisting of all elements
java.lang.Class	getCharacterDataClass() returns the class of the corresponding (i.e.
java.lang.Class	getCharacterDistributionClass() returns the Adjustable class of the corresponding (i.e.
java.lang.Class	getCharacterHistoryClass() returns the class of the corresponding (i.e.
java.lang.String	getDataTypeName() returns the name of the type of data stored
int	getMaxPossibleState() returns the maximum possible state
static int	getMaxPossibleStateStatic() returns the maximum possible state
java.lang.Class	getMCharactersDistributionClass() returns the Adjustable class of the corresponding (i.e.
static int	getOnlyElement(long s) Returns the only element in state set s.
static int	getTotalBitsInStateSet()
long	getValue() gets the value of the state set
static boolean	hasMultipleStates(long s) returns whether number of states in state set s is greater than 1
static long	intersection(long s1, long s2) return the result of taking the intersection of two states
boolean	isCombinable() returns whether value is combinable (i.e.
static boolean	isCombinable(long s) returns whether value is combinable (i.e.
boolean	isElement(int e) returns true iff e is element in state set
static boolean	isElement(long s, int e) returns true iff e is element in state set s
static boolean	isEmpty(long s) returns state set
boolean	isImpossible() returns whether value is valid or not.
static boolean	isImpossible(long s) returns whether value is valid or not.
boolean	isInapplicable() returns true iff state set is inapplicable
static boolean	isInapplicable(long s) returns true iff state set passed is inapplicable.
boolean	isLowerCase() return whether uncertainty flag is set in state set s
static boolean	isLowerCase(long s) return whether uncertainty flag is set in state set s
static boolean	isOnlyElement(long s, int e) returns true if e is only state in state set s
static boolean	isSubset(long sub, long s) returns true iff the first long is a subset of the second
boolean	isUnassigned() returns true iff stateset is unassigned (missing data)
static boolean	isUnassigned(long s) returns true iff state set passed is unassigned (missing data)
static boolean	isUnassignedInt(int s) return whether uncertainty flag is set in state set s
static boolean	isUncertain(long s) return whether uncertainty flag is set in state set s
static boolean	legalState(int e) returns whether state is within allowed range.
AdjustableDistribution	makeAdjustableDistribution(Taxa taxa, int numNodes) returns a AdjustableDistribution that is equivalent to this character type (i.e., in which sort of matrix would this character state reside?
CharacterHistory	makeCharacterHistory(Taxa taxa, int numNodes) returns a CharacterHistory that is equivalent to this character type (i.e., in which sort of matrix would this character state reside?
static long	makeSet(int e) returns a state set including only the state e
static long	makeSet(int e1, int e2) returns a state set including only the states e1 & e2
static long	makeSet(int e1, int e2, int e3) returns a state set including only the states e1 & e2 & e3
static long	makeSet(int e1, int e2, int e3, int e4) returns a state set including only the states e1 & e2 & e3 & e4
static long	makeSetFromLowerBits(int shortS) returns a state set including only elements in shortS; if shortS has multiple elements, the uncertainty bit is set.
static int	maximum(long s) return maximum value of states in state set s
static long	mergeStates(long s1, long s2) merges the states
static int	minimum(long s) returns minimum element in state set s
static CategoricalState	newState() returns new state
static long	nextSet(long current, int maxS) When passed a set, returns the next set in sequence with the same number of elements and with maximum element maxS.
static long	setInapplicable(long s, boolean b) Adds or clears the inapplicable bit of state set s , used for merging operations
static long	setLowerCase(long s, boolean lowerCase) return the result of setting or clearing the lowerCase flag of state set s
void	setToInapplicable() sets the value to inapplicable
void	setToUnassigned() sets the value to unassigned
static long	setUnassigned(long s, boolean b) Adds or clears the unassigned bit of state set s , used for merging operations
static long	setUncertainty(long s, boolean uncertain) return the result of setting or clearing the uncertainty flag of state set s
void	setValue(CharacterState cs) sets the value using the passed CharacterState's value if of same type
void	setValue(long value) sets the value of the state set to the long variable passed
void	setValue(java.lang.String s, CharacterData parentData) sets its value to the value given by the String passed to it
void	setValue(java.lang.String s, MesquiteInteger pos) sets its value to the value given by the String passed to it starting at position pos �
static long	span(int a, int b) return a state set with all states a through b inclusive.
static long	span(long s) returns the state set spanning min to max of s
boolean	statesShared(CategoricalState cs) return whether or not the two state sets share any states
static boolean	statesShared(long s1, long s2) return whether or not the two state sets share any states
java.lang.String	toDisplayString() Returns string as would be displayed to user (not necessarily internal shorthand).
java.lang.String	toNEXUSString() converts passed long (treated as CategoricalState) to string.
static java.lang.String	toNEXUSString(long s) converts passed long (treated as CategoricalState) to string.
static java.lang.String	toSimpleString(long s) converts passed long (treated as CategoricalState) to string.
static java.lang.String	toSimpleStringHB(long s) converts passed long (treated as CategoricalState) to string.
java.lang.String	toString() returns the String description of the state set
static java.lang.String	toString(long s) converts passed long (treated as CategoricalState) to string.
static java.lang.String	toString(long s, boolean useBraces) converts passed long (treated as CategoricalState) to string.
static java.lang.String	toString(long s, CategoricalData data, int ic, boolean useBraces) converts passed long (treated as CategoricalState) to string.
static java.lang.String	toString(long s, CategoricalData data, int ic, boolean useBraces, boolean useSymbols) converts passed long (treated as CategoricalState) to string.
static long	union(long s1, long s2) return the result of taking the union of two states
int	whichState(char c)

Methods inherited from class mesquite.lib.characters.CharacterState

makeMCharactersDistribution

Methods inherited from class java.lang.Object

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

Field Detail

unassigned

public static final long unassigned

The state (1L<<63) that corresponds to missing data.

See Also:

Constant Field Values

inapplicable

public static final long inapplicable

The state that corresponds to a gap (inapplicable)

See Also:

Constant Field Values

impossible

public static final long impossible

The state (1L<<62) that corresponds to an invalid CategoricalState.

See Also:

Constant Field Values

polymorphismElement

public static final int polymorphismElement

a value for arrays that store information about frequency of states; this would need to change if ever maxCategoricalState goes to 58

See Also:

Constant Field Values

unassignedBit

public static final int unassignedBit

The bit that signals missing data

See Also:

Constant Field Values

inapplicableBit

public static final int inapplicableBit

The bit that signals a gap (inapplicable)

See Also:

Constant Field Values

uncertainBit

public static final int uncertainBit

The bit that signals uncertainty

See Also:

Constant Field Values

lowerCaseBit

public static final int lowerCaseBit

The bit that signals the symbol is to be shown lower case

See Also:

Constant Field Values

maxCategoricalState

public static final int maxCategoricalState

The maximum allowed categorical state (55)

See Also:

Constant Field Values

highBitsMask

public static final long highBitsMask

The mask that preserves the high bits used for special flags

See Also:

Constant Field Values

statesBitsMask

public static final long statesBitsMask

The mask that preserves bits 0.. maxCategoricalState

See Also:

Constant Field Values

dataBitsMask

public static final long dataBitsMask

The mask that preserves bits 0.. maxCategoricalState and the unassigned, impossible and uncertain bits

See Also:

Constant Field Values

unassignedBitInt

public static final int unassignedBitInt

Bits to be used if int used instead of long for state storage

See Also:

Constant Field Values

inapplicableBitInt

public static final int inapplicableBitInt

See Also:

Constant Field Values

uncertainBitInt

public static final int uncertainBitInt

See Also:

Constant Field Values

statesBitsMaskInt

public static final int statesBitsMaskInt

See Also:

Constant Field Values

TOTALBITS

public static final int TOTALBITS

See Also:

Constant Field Values

shortStatesBitsMaskL

public static final long shortStatesBitsMaskL

The masks that preserves bits 0.. maxCategoricalState

See Also:

Constant Field Values

intStatesBitsMaskL

public static final long intStatesBitsMaskL

See Also:

Constant Field Values

Constructor Detail

CategoricalState

public CategoricalState()

CategoricalState

public CategoricalState(long initial)

Method Detail

getDataTypeName

public java.lang.String getDataTypeName()

returns the name of the type of data stored

Specified by:

getDataTypeName in class CharacterState

getCharacterDataClass

public java.lang.Class getCharacterDataClass()

returns the class of the corresponding (i.e. of same data type) CharacterData object (in this case, CategoricalData.class).

Specified by:

getCharacterDataClass in class CharacterState

getMCharactersDistributionClass

public java.lang.Class getMCharactersDistributionClass()

returns the Adjustable class of the corresponding (i.e. of same data type) MCharactersDistribution object (in this case, MCategoricalAdjustable.class).

Specified by:

getMCharactersDistributionClass in class CharacterState

getCharacterDistributionClass

public java.lang.Class getCharacterDistributionClass()

returns the Adjustable class of the corresponding (i.e. of same data type) CharacterDistribution object (in this case, CategoricalAdjustable.class).

Specified by:

getCharacterDistributionClass in class CharacterState

getCharacterHistoryClass

public java.lang.Class getCharacterHistoryClass()

returns the class of the corresponding (i.e. of same data type) CharacterHistory object (in this case, CategoricalHistory.class).

Specified by:

getCharacterHistoryClass in class CharacterState

makeAdjustableDistribution

public AdjustableDistribution makeAdjustableDistribution(Taxa taxa,
                                                         int numNodes)

Description copied from class: CharacterState

returns a AdjustableDistribution that is equivalent to this character type (i.e., in which sort of matrix would this character state reside?

Specified by:

makeAdjustableDistribution in class CharacterState

makeCharacterHistory

public CharacterHistory makeCharacterHistory(Taxa taxa,
                                             int numNodes)

Description copied from class: CharacterState

returns a CharacterHistory that is equivalent to this character type (i.e., in which sort of matrix would this character state reside?

Specified by:

makeCharacterHistory in class CharacterState

isUnassigned

public static boolean isUnassigned(long s)

returns true iff state set passed is unassigned (missing data)

isUnassigned

public boolean isUnassigned()

returns true iff stateset is unassigned (missing data)

Specified by:

isUnassigned in class CharacterState

isInapplicable

public static boolean isInapplicable(long s)

returns true iff state set passed is inapplicable.

isInapplicable

public boolean isInapplicable()

returns true iff state set is inapplicable

Specified by:

isInapplicable in class CharacterState

isImpossible

public boolean isImpossible()

returns whether value is valid or not.

Specified by:

isImpossible in class CharacterState

isImpossible

public static boolean isImpossible(long s)

returns whether value is valid or not.

isCombinable

public boolean isCombinable()

returns whether value is combinable (i.e. a valid assigned state) or not.

Specified by:

isCombinable in class CharacterState

isCombinable

public static boolean isCombinable(long s)

returns whether value is combinable (i.e. a valid assigned state) or not.

legalState

public static boolean legalState(int e)

returns whether state is within allowed range.

equals

public boolean equals(CharacterState s)

returns true iff state sets are same

Specified by:

equals in class CharacterState

equals

public boolean equals(CharacterState s,
                      boolean allowMissing)

returns true iff state sets are same

Specified by:

equals in class CharacterState

equals

public boolean equals(CharacterState s,
                      boolean allowMissing,
                      boolean allowNearExact)

returns true iff state sets are same

Specified by:

equals in class CharacterState

equals

public boolean equals(CharacterState s,
                      boolean allowMissing,
                      boolean allowNearExact,
                      boolean allowSubset)

returns true iff state sets are same

Overrides:

equals in class CharacterState

newState

public static CategoricalState newState()

returns new state

isEmpty

public static boolean isEmpty(long s)

returns state set

emptySet

public static long emptySet()

returns state set

fullSet

public static long fullSet()

returns state set consisting of all elements

firstSet

public static long firstSet(int numInSet)

Returns the set that is {0,...,(numInSet-1)} That is, the first "numInSet" bits are set. This is designed for use with next set, to generate for instance all possible sets containing numInSet elements

nextSet

public static long nextSet(long current,
                           int maxS)

When passed a set, returns the next set in sequence with the same number of elements and with maximum element maxS. This can be called repeatedly (after starting with firstSet) to generate all sets with a certain number of elements. When the current set is the last one, returns an empty set.

isElement

public boolean isElement(int e)

returns true iff e is element in state set

isElement

public static boolean isElement(long s,
                                int e)

returns true iff e is element in state set s

isSubset

public static boolean isSubset(long sub,
                               long s)

returns true iff the first long is a subset of the second

minimum

public static int minimum(long s)

returns minimum element in state set s

getOnlyElement

public static int getOnlyElement(long s)

Returns the only element in state set s. If more than one element, or no elements, returns -1.

cardinality

public static int cardinality(int shortS)

returns number of states in state set shortS

cardinality

public static int cardinality(long s)

returns number of states in state set s

cardinality

public int cardinality()

returns number of states in state set

hasMultipleStates

public static boolean hasMultipleStates(long s)

returns whether number of states in state set s is greater than 1

maximum

public static int maximum(long s)

return maximum value of states in state set s

isOnlyElement

public static boolean isOnlyElement(long s,
                                    int e)

returns true if e is only state in state set s

makeSet

public static long makeSet(int e)

returns a state set including only the state e

makeSetFromLowerBits

public static long makeSetFromLowerBits(int shortS)

returns a state set including only elements in shortS; if shortS has multiple elements, the uncertainty bit is set.

makeSet

public static long makeSet(int e1,
                           int e2)

returns a state set including only the states e1 & e2

makeSet

public static long makeSet(int e1,
                           int e2,
                           int e3)

returns a state set including only the states e1 & e2 & e3

makeSet

public static long makeSet(int e1,
                           int e2,
                           int e3,
                           int e4)

returns a state set including only the states e1 & e2 & e3 & e4

span

public static long span(int a,
                        int b)

return a state set with all states a through b inclusive.

span

public static long span(long s)

returns the state set spanning min to max of s

mergeStates

public static long mergeStates(long s1,
                               long s2)

merges the states

setInapplicable

public static long setInapplicable(long s,
                                   boolean b)

Adds or clears the inapplicable bit of state set s , used for merging operations

setUnassigned

public static long setUnassigned(long s,
                                 boolean b)

Adds or clears the unassigned bit of state set s , used for merging operations

setLowerCase

public static long setLowerCase(long s,
                                boolean lowerCase)

return the result of setting or clearing the lowerCase flag of state set s

isLowerCase

public static boolean isLowerCase(long s)

return whether uncertainty flag is set in state set s

isLowerCase

public boolean isLowerCase()

return whether uncertainty flag is set in state set s

setUncertainty

public static long setUncertainty(long s,
                                  boolean uncertain)

return the result of setting or clearing the uncertainty flag of state set s

isUncertain

public static boolean isUncertain(long s)

return whether uncertainty flag is set in state set s

addToSet

public static long addToSet(long s,
                            int e)

return the result of adding state e to state set s

union

public static long union(long s1,
                         long s2)

return the result of taking the union of two states

intersection

public static long intersection(long s1,
                                long s2)

return the result of taking the intersection of two states

statesShared

public static boolean statesShared(long s1,
                                   long s2)

return whether or not the two state sets share any states

statesShared

public boolean statesShared(CategoricalState cs)

return whether or not the two state sets share any states

clearFromSet

public static long clearFromSet(long s,
                                long e)

return the result of subtracting state e to state set s

clearFromSet

public static long clearFromSet(long s,
                                int e)

return the result of subtracting state e to state set s

chooseHighestWithinFactor

public static long chooseHighestWithinFactor(double[] values,
                                             double factor)

chooseHighest

public static long chooseHighest(double[] values,
                                 double toleranceProportion)

chooseLowest

public static long chooseLowest(double[] values,
                                double toleranceProportion)

compressibleToShort

public static boolean compressibleToShort(long s)

compressToShort

public static short compressToShort(long s)

expandFromShort

public static long expandFromShort(short s)

compressibleToInt

public static boolean compressibleToInt(long s)

compressToInt

public static int compressToInt(long s)

expandFromInt

public static long expandFromInt(int s)

expand

public static int[] expand(long s)

Expands state set (passed as long) to full array of included elements.

compressFromList

public static long compressFromList(int[] states)

Compresses array listing included elements into state set form (long, with bits set). This is inverse of expand.

compressFromPresence

public static long compressFromPresence(double[] states)

Compresses array with presence (>0) or absence (<=0) for each element into state set form (long, with bits set).

setToInapplicable

public void setToInapplicable()

sets the value to inapplicable

Specified by:

setToInapplicable in class CharacterState

setToUnassigned

public void setToUnassigned()

sets the value to unassigned

Specified by:

setToUnassigned in class CharacterState

getValue

public long getValue()

gets the value of the state set

setValue

public void setValue(long value)

sets the value of the state set to the long variable passed

setValue

public void setValue(CharacterState cs)

sets the value using the passed CharacterState's value if of same type

Specified by:

setValue in class CharacterState

setValue

public void setValue(java.lang.String s,
                     MesquiteInteger pos)

sets its value to the value given by the String passed to it starting at position pos �

Specified by:

setValue in class CharacterState

setValue

public void setValue(java.lang.String s,
                     CharacterData parentData)

Description copied from class: CharacterState

sets its value to the value given by the String passed to it

Specified by:

setValue in class CharacterState

fromChar

public long fromChar(char c)

return the state set containing the state represented by the character (e.g., '0' to {0}); Used default symbols since no CharacterData is specified �

whichState

public int whichState(char c)

toString

public java.lang.String toString()

returns the String description of the state set

Specified by:

toString in class CharacterState

toString

public static java.lang.String toString(long s)

converts passed long (treated as CategoricalState) to string. Uses braces, and does not use character state names

toString

public static java.lang.String toString(long s,
                                        boolean useBraces)

converts passed long (treated as CategoricalState) to string. Does not use character state names

toString

public static java.lang.String toString(long s,
                                        CategoricalData data,
                                        int ic,
                                        boolean useBraces)

converts passed long (treated as CategoricalState) to string. Uses character state names if available.

toString

public static java.lang.String toString(long s,
                                        CategoricalData data,
                                        int ic,
                                        boolean useBraces,
                                        boolean useSymbols)

converts passed long (treated as CategoricalState) to string. Uses character state names if available. �

toDisplayString

public java.lang.String toDisplayString()

Returns string as would be displayed to user (not necessarily internal shorthand). �

Specified by:

toDisplayString in class CharacterState

toSimpleString

public static java.lang.String toSimpleString(long s)

converts passed long (treated as CategoricalState) to string. Uses default symbols for states.

toNEXUSString

public java.lang.String toNEXUSString()

converts passed long (treated as CategoricalState) to string. Uses default symbols for states.

toNEXUSString

public static java.lang.String toNEXUSString(long s)

converts passed long (treated as CategoricalState) to string. Uses default symbols for states.

toSimpleStringHB

public static java.lang.String toSimpleStringHB(long s)

converts passed long (treated as CategoricalState) to string. Uses default symbols for states. Includes High Bits. Used for development/debugging. �

getMaxPossibleStateStatic

public static int getMaxPossibleStateStatic()

returns the maximum possible state

getTotalBitsInStateSet

public static int getTotalBitsInStateSet()

getMaxPossibleState

public int getMaxPossibleState()

returns the maximum possible state

isUnassignedInt

public static boolean isUnassignedInt(int s)

return whether uncertainty flag is set in state set s