NEXUS CLASS LIBRARY: NxsDistancesBlock Class

NEXUS CLASS LIBRARY | home | classes | functions

# Class NxsDistancesBlock

## Enums

NxsDistancesBlockEnum

## Data Members

diagonal, interleave, labels, matrix, missing, nchar, newtaxa, ntax, taxa, taxonPos, triangle

## Member Functions

GetDistance, GetMissingSymbol, GetNchar, GetNtax, GetTriangle, HandleDimensionsCommand, HandleFormatCommand, HandleMatrixCommand, HandleNextPass, HandleTaxlabelsCommand, IsDiagonal, IsInterleave, IsLabels, IsLowerTriangular, IsMissing, IsRectangular, IsUpperTriangular, NxsDistancesBlock, ~NxsDistancesBlock, Read, Report, Reset, SetDistance, SetMissing, SetNchar

## Class Description

This class handles reading and storage for the NEXUS block DISTANCES. It overrides the member functions Read and Reset, which are abstract virtual functions in the base class NxsBlock . Below is a table showing the correspondence between the elements of a DISTANCES block and the variables and member functions that can be used to access each piece of information stored.

     NEXUS command   Command attribute  Data Members        Member Functions
     ------------------------------------------------------------------------
     DIMENSIONS      NEWTAXA            newtaxa

                     NTAX               ntax                GetNtax

                     NCHAR              nchar               GetNchar

     FORMAT          TRIANGLE           triangle            GetTriangle
                                                            IsUpperTriangular
                                                            IsLowerTriangular
                                                            IsRectangular

                     [NO]DIAGONAL       diagonal            IsDiagonal

                     [NO]LABELS         labels              IsLabels

                     MISSING            missing             GetMissingSymbol

                     INTERLEAVE         interleave          IsInterleave

                     TAXLABELS          (stored in the      (access through
     				                    NxsTaxaBlock         data member taxa)
     								   object)

     MATRIX                             matrix              GetDistance
                                                            IsMissing
                                                            SetMissing
                                                            SetDistance
     ------------------------------------------------------------------------

### Key to symbols and colors

public, protected, private, `A` = abstract, `C` = constructor, `D` = destructor, `I` = inline, `S` = static, `V` = virtual, `F` = friend

Enums

`enum NxsDistancesBlockEnum` |
| `upper = 1`
|  | matrix is upper-triangular
| `lower = 2`
|  | matrix is lower-triangular
| `both = 3`
|  | matrix is rectangular

Data Members

|  | `bool` |  | `diagonal`
|  |  |  | true if diagonal elements provided when reading in DISTANCES block
|  | `bool` |  | `interleave`
|  |  |  | true if interleave format used when reading in DISTANCES block
|  | `bool` |  | `labels`
|  |  |  | true if taxon labels were provided when reading in DISTANCES block
|  | `NxsDistanceDatum` |  | `**matrix`
|  |  |  | the structure used for storing the pairwise distance matrix
|  | `char` |  | `missing`
|  |  |  | the symbol used to represent missing data (e.g. '?')
|  | `unsigned` |  | `nchar`
|  |  |  | the number of characters used in generating the pairwise distances
|  | `bool` |  | `newtaxa`
|  |  |  | true if new taxa were named in this DISTANCES block
|  | `unsigned` |  | `ntax`
|  |  |  | number of taxa (determines dimensions of the matrix)
|  | `NxsTaxaBlock` |  | `*taxa`
|  |  |  | pointer to NxsTaxaBlock object that stores the taxon labels
|  | `unsigned` |  | `*taxonPos`
|  |  |  | array holding 0-offset index into the NxsTaxaBlock list of taxon labels (used to ensure that order of taxa is same for each interleaved block)
|  | `int` |  | `triangle`
|  |  |  | indicates whether matrix is upper triangular, lower triangular, or rectangular, taking on one of the elements of the NxsDistancesBlockEnum enumeration

Member Functions

|  | `double` |  | `GetDistance``(unsigned i, unsigned j)`
|  |  |  | Returns the value of the (i, j)th element of matrix. Assumes i and j are both in the range [0..ntax) and the distance stored at `matrix[i][j]' is not missing. Also assumes matrix is not NULL.
|  | `char` |  | `GetMissingSymbol``()`
|  |  |  | Returns the value of missing.
|  | `unsigned` |  | `GetNchar``()`
|  |  |  | Returns the value of nchar.
|  | `unsigned` |  | `GetNtax``()`
|  |  |  | Returns the value of ntax.
|  | `unsigned` |  | `GetTriangle``()`
|  |  |  | Returns the value of triangle.
|  | `void` |  | `HandleDimensionsCommand``(NxsToken &token)`
|  |  |  | Called when DIMENSIONS command needs to be parsed from within the DISTANCES block. Deals with everything after the token DIMENSIONS up to and including the semicolon that terminates the DIMENSIONS command.
|  | `void` |  | `HandleFormatCommand``(NxsToken &token)`
|  |  |  | Called when FORMAT command needs to be parsed from within the DISTANCES block. Deals with everything after the token FORMAT up to and including the semicolon that terminates the FORMAT command.
|  | `void` |  | `HandleMatrixCommand``(NxsToken &token)`
|  |  |  | Called when MATRIX command needs to be parsed from within the DISTANCES block. Deals with everything after the token MATRIX up to and including the semicolon that terminates the MATRIX command.
|  | `bool` |  | `HandleNextPass``(NxsToken &token, unsigned &offset)`
|  |  |  | Called from within HandleMatrix, this function is used to deal with interleaved matrices. It is called once for each pass through the taxa. The local variable jmax records the number of columns read in the current interleaved page and is used to determine the offset used for j in subsequent pages.
|  | `void` |  | `HandleTaxlabelsCommand``(NxsToken &token)`
|  |  |  | Called when TAXLABELS command needs to be parsed from within the DISTANCES block. Deals with everything after the token TAXLABELS up to and including the semicolon that terminates the TAXLABELS command.
|  | `bool` |  | `IsDiagonal``()`
|  |  |  | Returns the value of diagonal.
|  | `bool` |  | `IsInterleave``()`
|  |  |  | Returns the value of interleave.
|  | `bool` |  | `IsLabels``()`
|  |  |  | Returns the value of labels.
|  | `bool` |  | `IsLowerTriangular``()`
|  |  |  | Returns true if the value of triangle is NxsDistancesBlockEnum(lower), false otherwise.
|  | `bool` |  | `IsMissing``(unsigned i, unsigned j)`
|  |  |  | Returns true if the (i,j)th distance is missing. Assumes i and j are both in the range [0..ntax) and matrix is not NULL.
|  | `bool` |  | `IsRectangular``()`
|  |  |  | Returns true if the value of triangle is NxsDistancesBlockEnum(both), false otherwise.
|  | `bool` |  | `IsUpperTriangular``()`
|  |  |  | Returns true if the value of triangle is NxsDistancesBlockEnum(upper), false otherwise.
C |  | `` |  | `NxsDistancesBlock``(NxsTaxaBlock *t)`
|  |  |  | Sets id to "DISTANCES", taxa to t, triangle to `NxsDistancesBlockEnum::lower', missing to '?', matrix and taxonPos to NULL, labels and diagonal to true, newtaxa and interleave to false, and ntax and nchar to 0. Assumes t is non-NULL.
D |  | `` |  | `~NxsDistancesBlock``()`
|  |  |  | Deletes matrix and taxonPos arrays.
V |  | `void` |  | `Read``(NxsToken &token)`
|  |  |  | This function provides the ability to read everything following the block name (which is read by the NEXUS object) to the end or endblock statement. Characters are read from the input stream in. Overrides the abstract virtual function in the base class.
V |  | `void` |  | `Report``(ostream &out)`
|  |  |  | This function outputs a brief report of the contents of this taxa block. Overrides the abstract virtual function in the base class.
V |  | `void` |  | `Reset``()`
|  |  |  | Flushes taxonLabels and sets ntax to 0 in preparation for reading a new TAXA block.
|  | `void` |  | `SetDistance``(unsigned i, unsigned j, double d)`
|  |  |  | Sets the value of the (i,j)th matrix element to d and missing to false . Assumes i and j are both in the range [0..ntax) and matrix is not NULL.
|  | `void` |  | `SetMissing``(unsigned i, unsigned j)`
|  |  |  | Sets the value of the (i, j)th matrix element to missing. Assumes i and j are both in the range [0..ntax) and matrix is not NULL.
|  | `void` |  | `SetNchar``(unsigned n)`
|  |  |  | Sets nchar to n.