pal.misc
Class TimeOrderCharacterData

java.lang.Object
  extended by pal.misc.TimeOrderCharacterData
All Implemented Interfaces:
java.io.Serializable, BranchLimits, IdGroup, Units, UnitsProvider

public class TimeOrderCharacterData
extends java.lang.Object
implements java.io.Serializable, BranchLimits, UnitsProvider, IdGroup

Character data that expresses an order through time.

Version:
$Id: TimeOrderCharacterData.java,v 1.21 2004/01/15 01:18:32 matt Exp $
Author:
Alexei Drummond
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from interface pal.misc.IdGroup
IdGroup.Utils
 
Field Summary
protected  pal.misc.TimeOrderCharacterData.SubgroupHandler[] subgroups_
           
protected  IdGroup taxa
          the identifier group
protected  int[] timeOrdinals
          Order of times
protected  double[] times
          Actual times of each sample
protected  int units
           
 
Fields inherited from interface pal.misc.BranchLimits
ABSTOL, DEFAULT_LENGTH, FRACDIGITS, MAXARC, MINARC
 
Fields inherited from interface pal.misc.Units
DAYS, EXPECTED_SUBSTITUTIONS, GENERATIONS, MONTHS, SAMPLE, SHORT_UNIT_NAMES, UNIT_NAMES, UNKNOWN, YEARS
 
Constructor Summary
protected TimeOrderCharacterData()
          Parameterless constructor for superclasses.
  TimeOrderCharacterData(IdGroup taxa, int units)
          Constructor taking only IdGroup.
  TimeOrderCharacterData(IdGroup taxa, int units, boolean contemp)
          Constructor taking only IdGroup.
  TimeOrderCharacterData(int numSeqsPerSample, int numSamples, double timeBetweenSamples, int units)
          Constructs a TimeOrderCharacterData with a number of equal-sized, evenly-spaced sampling times.
 
Method Summary
static TimeOrderCharacterData clone(TimeOrderCharacterData tocd)
          Returns a clone of the specified TimeOrderCharacterData
 TimeOrderCharacterData createSubgroup(int subgroupNumber)
          Creates a TimeOrderCharacterData which is a subset of this sub group.
 TimeOrderCharacterData generateDummyTimedTOCD(double[] sampleRates)
           
 TimeOrderCharacterData generateExpectedSubsitutionsTimedTOCD(double[] sampleRates)
          Given an array of rates between samples (matching exactly the samples in order) then produces a TimeOrderCharacterData object that is timed by Expected Substitutions.
 double[] getCopyOfTimes()
          Returns a copy of the times in the form of an array.
 double getHeight(int taxon, double rate)
          NOTE: currently assumes times exist!
 int getIdCount()
          Returns the number of identifiers in this group
 Identifier getIdentifier(int i)
          Returns the ith identifier.
 IdGroup getIdGroup()
          Deprecated. TimeOrderCharacterData now implements IdGroup
 double getMaximumTime()
           
 double getMinimumTime()
           
 java.lang.String getName()
          Returns a name for this character data.
 int getNumberOfSubgroups()
           
 int getNumChars()
          Returns the number of characters per identifier
 int getOrdinalCount()
           
 int[] getOrdinals()
          Gets ordinals.
 double getOrdinalTime(int ordinal)
          Obtain the time of a particular ordinal
 TimeOrderCharacterData getReordered(IdGroup base)
          Creates a new TimeOrderCharacterData object with the same properites as this one but the identifier positions match that of base (ie whichIdNumber(Name) returns the same as for base)
 int getSampleCount()
          Deprecated. Use getOrdinalCount()
 Identifier[] getSubgroupMembers(int subgroupNumber)
           
 double getSuggestedMaximumMutationRate()
          A simple utility method for generating a maximu mutation rate based on times.
 double getTime(int taxon)
           
 double getTime(java.lang.String taxonName)
           
 int getTimeOrdinal(Identifier taxonName)
           
 int getTimeOrdinal(int taxon)
           
 int getTimeOrdinal(java.lang.String taxonName)
           
 double[] getUniqueTimeArray()
          Returns an ordered vector of unique times in this time order character data.
 double[][] getUniqueTimeMatrix()
          Returns a matrix of times between samples.
 int getUnits()
           
 boolean hasSubgroups()
           
 boolean hasTimes()
           
 void removeTimes()
          Remove time character data.
 TimeOrderCharacterData scale(double rate, int newUnits)
           
 void setIdentifier(int i, Identifier ident)
          Sets the ith identifier.
 void setName(java.lang.String name)
          Sets the name of this character data.
 void setOrdinals(int[] ordinals)
          Sets ordinals.
 void setOrdinals(TimeOrderCharacterData tocd)
          Set time ordinals from another TimeOrderCharacterData.
 void setOrdinals(TimeOrderCharacterData tocd, IdGroup standard, boolean doTimes)
          Set time ordinals from another TimeOrderCharacterData.
 void setSubgroup(int[] subgroup)
          A means for define a subgroup.
 void setSubgroup(java.lang.String[] subgroup)
          A means for define a subgroup.
 void setSubgroups(int[][] subgroups)
          A means for define a subgroup.
 void setSubgroups(java.lang.String[][] subgroups)
          A means for define subgroups.
 void setTimes(double[] times, int units)
          Sets the times, and works out what the ordinals should be.
 void setTimes(double[] times, int units, boolean recalculateOrdinals)
          Sets the times.
 void setTimesAndOrdinals(TimeOrderCharacterData tocd)
           
 void shuffleTimes()
           
 TimeOrderCharacterData subset(IdGroup staxa)
          Extracts a subset of a TimeOrderCharacterData.
 java.lang.String toString()
          Returns a string representation of this time order character data.
 int whichIdNumber(java.lang.String name)
          returns the index of the identifier with the given name.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

timeOrdinals

protected int[] timeOrdinals
Order of times


times

protected double[] times
Actual times of each sample


taxa

protected IdGroup taxa
the identifier group


units

protected int units

subgroups_

protected pal.misc.TimeOrderCharacterData.SubgroupHandler[] subgroups_
Constructor Detail

TimeOrderCharacterData

protected TimeOrderCharacterData()
Parameterless constructor for superclasses.


TimeOrderCharacterData

public TimeOrderCharacterData(IdGroup taxa,
                              int units)
Constructor taking only IdGroup. Beware! This constructor does not initialize any time ordinals or times.

Parameters:
taxa - the taxa that this time data relates to.
units - the units of the times.

TimeOrderCharacterData

public TimeOrderCharacterData(IdGroup taxa,
                              int units,
                              boolean contemp)
Constructor taking only IdGroup.

Parameters:
taxa - the taxa that this time data relates to.
units - the units of the times.
contemp - if true, all times are set to zero, else times are not set.

TimeOrderCharacterData

public TimeOrderCharacterData(int numSeqsPerSample,
                              int numSamples,
                              double timeBetweenSamples,
                              int units)
Constructs a TimeOrderCharacterData with a number of equal-sized, evenly-spaced sampling times.

Parameters:
numSeqsPerSample - the number of taxa/sequences per sample time.
numSamples - the number of sample times.
timeBetweenSamples - the time between each pair of consecutive samples.
units - the units in which the times are expressed.
Method Detail

clone

public static TimeOrderCharacterData clone(TimeOrderCharacterData tocd)
Returns a clone of the specified TimeOrderCharacterData


subset

public TimeOrderCharacterData subset(IdGroup staxa)
Extracts a subset of a TimeOrderCharacterData.


getUnits

public int getUnits()
Specified by:
getUnits in interface UnitsProvider
Returns:
the units relating to this object.

setSubgroups

public final void setSubgroups(int[][] subgroups)
A means for define a subgroup.

Parameters:
subgroups - an array of integer arrays. Each array holds the indexes of the members that for that subgroup

setSubgroup

public final void setSubgroup(int[] subgroup)
A means for define a subgroup.

Parameters:
subgroups - an array indexes of the members that for the subgroup

setSubgroup

public final void setSubgroup(java.lang.String[] subgroup)
A means for define a subgroup.

Parameters:
subgroups - an array of names that represent the members of the subgroup.Non existent memebers are ignored

setSubgroups

public final void setSubgroups(java.lang.String[][] subgroups)
A means for define subgroups.

Parameters:
subgroups - an array of String arrays. Each array holds the members for a particular subgroup. Nonexistent members are ignored.

hasSubgroups

public final boolean hasSubgroups()

getNumberOfSubgroups

public final int getNumberOfSubgroups()

createSubgroup

public final TimeOrderCharacterData createSubgroup(int subgroupNumber)
Creates a TimeOrderCharacterData which is a subset of this sub group. Different subgroups may contain the same members


getSubgroupMembers

public final Identifier[] getSubgroupMembers(int subgroupNumber)

setTimes

public void setTimes(double[] times,
                     int units)
Sets the times, and works out what the ordinals should be.


setTimes

public void setTimes(double[] times,
                     int units,
                     boolean recalculateOrdinals)
Sets the times.

Parameters:
recalculateOrdinals - true if ordinals should be recalculated from the times.

scale

public TimeOrderCharacterData scale(double rate,
                                    int newUnits)

setOrdinals

public void setOrdinals(int[] ordinals)
Sets ordinals.


getMaximumTime

public double getMaximumTime()
Returns:
the maximum time

getMinimumTime

public double getMinimumTime()
Returns:
the minimum time

getOrdinals

public int[] getOrdinals()
Gets ordinals.


getCopyOfTimes

public double[] getCopyOfTimes()
Returns a copy of the times in the form of an array.


getReordered

public TimeOrderCharacterData getReordered(IdGroup base)
Creates a new TimeOrderCharacterData object with the same properites as this one but the identifier positions match that of base (ie whichIdNumber(Name) returns the same as for base)

Throws:
java.lang.IllegalArgumentException - if the base ids don't match the ids of this tocd

removeTimes

public void removeTimes()
Remove time character data.


generateExpectedSubsitutionsTimedTOCD

public TimeOrderCharacterData generateExpectedSubsitutionsTimedTOCD(double[] sampleRates)
Given an array of rates between samples (matching exactly the samples in order) then produces a TimeOrderCharacterData object that is timed by Expected Substitutions. Needs only sample information so no real time information required.


generateDummyTimedTOCD

public TimeOrderCharacterData generateDummyTimedTOCD(double[] sampleRates)
Returns:
a dummy time order character data base on this that does have times, but the times are set to match the sample number. Eg. Ids in sample 0 have time 0, ids in sample 1 have time 1, and so on. The Units are UNKNOWN

setOrdinals

public void setOrdinals(TimeOrderCharacterData tocd)
Set time ordinals from another TimeOrderCharacterData. Select ordinals by matching names.

Parameters:
tocd - to take ordinals from.

setTimesAndOrdinals

public void setTimesAndOrdinals(TimeOrderCharacterData tocd)

setOrdinals

public void setOrdinals(TimeOrderCharacterData tocd,
                        IdGroup standard,
                        boolean doTimes)
Set time ordinals from another TimeOrderCharacterData. Select ordinals by matching names.

Parameters:
tocd - to take ordinals from
idgroup - use these labels to match indices in given tocd.
doTimes - if set then sets times as well

getNumChars

public int getNumChars()
Returns the number of characters per identifier


getName

public java.lang.String getName()
Returns a name for this character data.


setName

public void setName(java.lang.String name)
Sets the name of this character data.


getTime

public double getTime(int taxon)

getOrdinalTime

public double getOrdinalTime(int ordinal)
Obtain the time of a particular ordinal

Parameters:
ordinal - The ordinal of interest
Returns:
The time of the input ordinal
Throws:
java.lang.IllegalArgumentException - If no such ordinal

getTime

public double getTime(java.lang.String taxonName)

getHeight

public double getHeight(int taxon,
                        double rate)
NOTE: currently assumes times exist!


getTimeOrdinal

public int getTimeOrdinal(int taxon)

getTimeOrdinal

public int getTimeOrdinal(java.lang.String taxonName)

getTimeOrdinal

public int getTimeOrdinal(Identifier taxonName)

hasTimes

public boolean hasTimes()

getUniqueTimeArray

public double[] getUniqueTimeArray()
Returns an ordered vector of unique times in this time order character data.


getUniqueTimeMatrix

public double[][] getUniqueTimeMatrix()
Returns a matrix of times between samples. A sample is any set of identifiers that have the same times.


getSampleCount

public int getSampleCount()
Deprecated. Use getOrdinalCount()

A sample is any set of identifiers that have the same times.

Returns:
the number of unique times in this data.

getOrdinalCount

public int getOrdinalCount()
Returns:
the number of unique times in this data.

toString

public java.lang.String toString()
Returns a string representation of this time order character data.

Overrides:
toString in class java.lang.Object

shuffleTimes

public void shuffleTimes()

getIdentifier

public Identifier getIdentifier(int i)
Description copied from interface: IdGroup
Returns the ith identifier.

Specified by:
getIdentifier in interface IdGroup

setIdentifier

public void setIdentifier(int i,
                          Identifier ident)
Description copied from interface: IdGroup
Sets the ith identifier.

Specified by:
setIdentifier in interface IdGroup

getIdCount

public int getIdCount()
Description copied from interface: IdGroup
Returns the number of identifiers in this group

Specified by:
getIdCount in interface IdGroup

whichIdNumber

public int whichIdNumber(java.lang.String name)
Description copied from interface: IdGroup
returns the index of the identifier with the given name.

Specified by:
whichIdNumber in interface IdGroup

getIdGroup

public IdGroup getIdGroup()
Deprecated. TimeOrderCharacterData now implements IdGroup

Return id group of this alignment.


getSuggestedMaximumMutationRate

public final double getSuggestedMaximumMutationRate()
A simple utility method for generating a maximu mutation rate based on times. This is not guarranteed to be the best method. If the times are small (ie total differenct < 1), the maximum Mutation Rate is high. If the times are large (eg total differenct > 1) the maximum Mutation Rate is low. IE. the aim is to keep the Expected substitutions (mu*t) range reasonable (<1)