Class Band

The class Band describes a point ("band") on a chromosome. It provides methods for ordering bands on chromosomes relative to each other and information used when drawing chromosomes.

Overview

Band
New()
New(Band: String, Optional MayContainUncertainties: Boolean = true)
atResolutionOf(Resolution: eResolutionLevel): String
checkExistence(): void
clone(): Object {Implements ICloneable.Clone}
CompareTo(obj: Object): Integer {Implements IComparable.CompareTo} 
compareTo(SecondBand: Band, MayContainUncertainties: Boolean): Integer 
equals(CompareBand: Band, Optional Strict: Boolean = False): Boolean
expandedBandsAtResolution(Resolution: eResolutionLevel): Bands
expandToResolution(Resolution: eResolutionLevel, MinimumBand: Band, MaximumBand: Band): Boolean
getArm: String
getArmWithoutUncertainty: String
getBand: String
getBandNumber: String
getBandOnly: String
getBandWithoutUncertainty: String
getBrokenLevel: Integer
getChromosome: String
getChromosomeWithoutUncertainty: String
getMaximumResolution: eResolutionLevel
getPaintColor: System.Drawing.Color
getPaintHeight: Integer
getPaintStyle: ePaintStyle
getPaintWidth: ePaintWidth
getRegionEnd: String
getRegionStart: String
hasUncertainty(): Boolean 
isCloserToPTerThan(CompareBand: Band): Boolean
increaseBrokenLevel: void
isCloserToPTerThan(CompareBand: Band, MayContainUncertainties: Boolean): Boolean
isMoreDistalThan(CompareBand: Band): Boolean
isOnOppositeArm(CompareBand: Band): Boolean
isRegion(): Boolean
isTerminus(): Boolean
toString(): String
toString(format: String): String

Programming Language

  • Microsoft Visual Basic .Net.

Availability

Constructors

Public Sub New()

This parameter-less constructor is needed for cloning purposes and must be public because of COM compatibility. It is not intended for normal use. DO NOT USE IT.

Public Sub New(ByRef Band As String, Optional ByVal MayContainUncertainties As Boolean = True)

Instantiates a new band object. "Band" contains the textual description of the band. If you are sure that the description is free of uncertainties (question marks, interval sign), you can set MayContainUncertainties to true in order to enhance performance.

Parameters

  • Band: a reference to a textual description of the band.
  • MayContainUncertainties: indicates if the analysis of the band must assume uncertainties (regions, question marks) to be present.

Exceptions

  • ArgumentException, if the band description is not correct.

Remarks

  • An "or" qualifier is translated into a region. Do not use the "or" qualifier with bands, if this behavior would impose problems.
  • If the band description is known to be free from uncertainties, MayContainUncertainties can be set to false in order to speed up the analysis.

Examples:

  • To initailise a band object for Band 22q112, knowing that the description does not contain uncertainties, use:

    • myBand = New Band("22q112", false)
  • To initailise a band object for Band ?5p14~15, which obviously contains uncertainties, use:

    • myBand = New Band("?5p14~15")

Interfaces

IComparable

is implemented with the compareTo function.

ICloneable

is implemented with the clone function.

Enumerations

The class does not provide enumerations.

Properties

Since the band object expects not to be changed essentially after its initialisation, all its properties are read-only. They were made availbale through their respective getPropertyName functions only (see below).

Methods

Public Function atResolutionOf(ByRef Resolution As eResolutionLevel) As String

Returns a string describing the band at the given ResolutionLevel. If the band description meets a lower resolution level only, an error is raised.

Return Value

  • a textual description of a band corresponding to this band at the given resolution level.

Parameters

Exceptions

  • Exception, if the desired resolution level is higher than the present resolution level of te band.

Remarks

  • This function can reduce the resolution of a band, but it can not expand it. For that purpose, use the function expandToResolution.

Examples

  • If band 9q22.3 is to be shown at 400 bphs, the function returns 9q22.
  • If band 9q22.3 is to be shown at 800 bphs, the function throws an exception.

Public Sub checkExistence()

Checks if the band was defined in the resources file. If it was not found, an exception is thrown.

Return Value

  • None

Exceptions

  • Exception, if the band was not defined in the resorces file.

Remarks

Public Function clone() As Object Implements ICloneable.Clone

Returns a copy of the Band object.

Return Value

  • A copy of the Band object.

Implements

Remarks

  • The band object does not contain data of reference type, cloning is done by copying all its class wide boolean and string variables.

Public Overridable Overloads Function CompareTo(ByVal obj As Object) As Integer Implements IComparable.CompareTo

Compares this instance to a specified Band object and returns an indication of their relative values.

Return Value

  • <-1: This band resides on a chromosome with lower number.
  • -1:  Both bands are on the same chromosome, but this one is closer to the p-terminus.
  • 0: The bands are equal.
  • +1:  Both bands are on the same chromosome, but this one is closer to the q-terminus.
  • >+1: This band resides on a chromosome with higher number.

Parameters

  • obj: the Band to be compared with this band.

Exceptions

Implements

Remarks

  • The sorting order of chromosome follows the specification given in "ISCN 1995" by F. Mitelman et al. Bands on the same chromosome are sorted along the plus strand, i.e. from p terminus to q terminus.

Public Overloads Function compareTo(ByRef SecondBand As Band, ByVal MayContainUncertainties As Boolean) As Integer

Compares this instance to a specified Band object and returns an indication of their relative values.

Return Value

  • <-1: This band resides on a chromosome with lower number.
  • -1:  Both bands are on the same chromosome, but this one is closer to the p-terminus.
  • 0: The bands are equal.
  • +1:  Both bands are on the same chromosome, but this one is closer to the q-terminus.
  • >+1: This band resides on a chromosome with higher number.

Parameters

  • SecondBand: the Band to be compared with this band.
  • MayContainUncertainties: indicates if both bands to be compared are known to be free from uncertainties (value: false) or may contain some uncertainties (default; value: true).

Remarks

  • The sorting order of chromosome follows the specification given in "ISCN 1995" by F. Mitelman et al. Bands on the same chromosome are sorted along the plus strand, i.e. from p terminus to q terminus.
  • This compareTo function is faster than the standard one, especially when MayContainUncertainties is false.

Public Overloads Function equals(ByRef CompareBand As Band, Optional ByVal Strict As Boolean = False) As Boolean

Two bands are regarded equal when they share the chromosome, the arm and all digits denoting band number.

If Strict is true, the bands must also share their uncertainties; otherwise, uncertainties are ignored.

Return Value

  • true, if both bands are found to be equal.
  • false, otherwise.

Parameters

  • CompareBand: the Band to be compared with this band.
  • Strict: indicates if both bands to be compared also have to share their uncertainties.

Examples

  • With strict set to false, 9q21 equals 9?q21.

Public Function expandedBandsAtResolution(ByRef Resolution As eResolutionLevel) As Bands

Returns a list of bands which correspond to the band description at the given resolution. This is not only true for given intervals, but also other bands may split into several sub bands at higher resolutions.

Return Value

  • a Bands object containing all bands covered by this band at the given resolution level.

Parameters

Remarks

  • The desired resultion may be more or less than the present resolution of the band.
  • If a band splits into subbands at the desired resolution, a list of those bands will be returned.

Examples

  • Band "9q22~31" expanded to 400 bphsreturns "9q22,9q31".
  • Band "9q22" expanded to 800 bphs returns "9q22.1,9q22.2,9q22.31,9q22.32,9q22.33".

Public Function expandToResolution(ByRef Resolution As eResolutionLevel, ByRef MinimumBand As Band, ByRef MaximumBand As Band) As Boolean

Returns the band closest to p-terminus ("MinimumBand") and the band closest to q-terminus ("MaximumBand") the given band corresponds to at the given resolution. The return value of the function is true, if MinimumBand and MaximumBand are equal, else false.

Return Value

  • true, ifd the band already meets the desired resolution level.
  • false, otherwise.

Parameters

  • Resolution: the desired resolution level. Valid values are defined in the enumeration ChromosomeData.eResolutionLevel.
  • MinimumBand: a reference to the most p-terminal band covered by this band at the desired resolution.
  • MaximumBand: a reference to the most q-terminal band covered by this band at the desired resolution.

Remarks

  • The desired resultion may be more or less than the present resolution of the band.
  • MinimumBand and MaximumBand are passed by reference and changed in this function.

Examples

  • Band "9q22~31" expanded to 400 bphs returns false, MinimumBand is "9q22", MaximumBand is "9q31".
  • Band "9q22" expanded to 800 bphs returns false, MinimumBand is "9q22.1", MaximumBand is "9q22.33".
  • Band "9q22" expanded to 400 bphs returns true, MinimumBand is "9q22", MaximumBand is "9q22".

getArm As String

The designation of the chromosome arm ("p" or "q", question marks may be present) the band resides on.

Property Value

  • the designation of the chromosome arm.

Remarks

  • question marks may be present.

Example

  • With band 13?q14, getArm returns "?q".

getArmWithoutUncertainty As String

The designation of the chromosome arm ("p" or "q") the band resides on, question marks are removed.

Property Value

  • the designation of the chromosome arm.

Remarks

  • question marks are removed.

Example

  • With band 13?q14, getArmWithoutUncertainty returns "q".

getBand As String

The full description of the band including chromosome, arm, and band number (if present). May show question marks and interval signs.

Property Value

  • a textual description of the band.

Remarks

  • The description is taken from the original input, hence it need not strictly comply with the ISCN.

Example

  • Example: 13?q14.

getBandNumber As String

The number of the band (may contain uncertainties).
 

Property Value

  • the number of the band.

Remarks

  • information on the chromosome and the arm are omitted.

Example

  • With band 13?q14, getBandNumber returns "14".

getBandOnly As String

The designation of arm and band (may contain uncertainties).
 

Property Value

  • the designation of arm and band.

Remarks

  • uncertainties may be present.

Example

  • With band 13?q14, getBandOnly returns "?q14".

getBandWithoutUncertainty As String

The full description of the band including chromosome, arm, and band number (if present). Uncertainties were removed.

Property Value

  • a textual description of the band including chromosome, arm, and band number without uncertainties.

Remarks

  • If the band describes a region, only the start point of the regionis shown, its end point is deleted.

Example

  • With band 13?q14, getBandWithoutUncertainty returns "13q14".
  • With band "9q22~31", getBandWithoutUncertainty returns "9q22".

getBrokenLevel As Integer

The broken level describes how often chromosomal breaks occured at this band. It is used for calculating the reduced height of the band for ideograms of derivative chromosomes; there, the factor is 2-Brokenlevel.

Property Value

  • the number of breaks at this band.

Example

  • In the derivative chromosome der(22)(22pter->22q11.2::9q34->9qter), the BrokenLevel of band 22q11.2 is 1.

getChromosome As String

Returns the number of the chromosome (may contain uncertainties).

Property Value

  • the number of the chromosome.

Remarks

  • a leading question mark may be present.

Example

  • With band 13?q14, getChromosome returns "13".
  • With band ?9q22, getChromosome returns "?9".

getChromosomeWithoutUncertainty As String

Returns the number of the chromosome without uncertainties.

Property Value

  • the number of the chromosome.

Remarks

  • leading question marks are removed.

Example

  • With band 13?q14, getChromosomeWithoutUncertainty returns "13".
  • With band ?9q22, getChromosomeWithoutUncertainty returns "9".

getMaximumResolution As eResolutionLevel

Returns the maximum value of the ResolutionLevel which the band description fulfills.

Property Value

  • the maximum value of the ResolutionLevel which the band description fulfills.

Remarks

Example

  • With band 13?q14, getMaximumResolution returns "Resolution400Bands".
  • With band 13q34, getMaximumResolution returns "Resolution800Bands".

getPaintColor As System.Drawing.Color

Returns the color to be used for drawing the chromosome. It is originally defined in the resource file for the chromosomes.

Property Value

  • the color to be used for drawing an ideogram of the chromosome.

Remarks

Example

  • With band 13q14, getPaintColor returns originally "DarkOrange".

getPaintHeight As Integer

Returns the height the band is drawn with. For human chromosomes, values were taken from the drawing in "ISCN 1995" by Mitelman et al., with 1 cm corresponding to 100 pixels, and stored in ChromosomeData.xml. The BrokenLevel is accounted for.

Property Value

  • the height the band is drawn with in an ideogram.

Remarks

  • if the BrokenLevel of the band is different from 0, the PaintHeight is reduced accordingly.

Example

  • With an unbroken band 13q14, getPaintHeight returns "83".
  • With a band 13q14 broken two times, getPaintHeight returns "21".

getPaintStyle As ePaintStyle

Returns the style for filling the bands area in the drawing.

Property Value

  • the style for filling the bands area in an ideogram.

Remarks

Example

  • With band 13q14, getPaintStyle returns "PaintStyleTransparent".
  • With band 13q21, getPaintStyle returns "PaintStyleFull".

getPaintWidth As ePaintWidth

Return the description of the width ("normal" or "satellite") the band is drawn with.

Property Value

  • the description of the width the band is drawn with.

Remarks

  • Values for PaintStyle are defined in the Enumeration ChromosomeData.ePaintWidth.
  • Centromeric regions do not require such a PaintWidth attribute, they are dealt with specially.

Example

  • With band 13q14, getPaintWidth returns "PaintWidthNormal".
  • With band 13p12, getPaintWidth returns "PaintWidthSatellite".

getRegionEnd As String

If the band description contains an interval, RegionEnd contains the arm and digits only of the end band of the interval.

Property Value

  • the arm and digits of the end band of the interval described by the band.
  • an empty string, if the band does not describe an interval.

Example

  • With band 13q22~32, getRegionEnd returns "q32".

getRegionStart As String

If the band description contains an interval, RegionStart contains the arm and digits only of the start band of the interval.

Property Value

  • the arm and digits of the start band of the interval described by the band.
  • an empty string, if the band does not describe an interval.

Example

  • With band 13q22~32, getRegionStart returns "q22".

Public Function hasUncertainty() As Boolean

Returns true when an uncertainty (question mark, interval sign) was discovered during analysis of the band descirption.

Return Value

  • true, if the band description contains uncertainties.
  • false, otherwise.

Example

  • With band 13q22~32, hasUncertainty returns "true".
  • With band 13q22, hasUncertainty returns "false".

Public sub increaseBrokenLevel()

Increases the BrokenLevel by 1 thus indicating another break in this band.

Public Function isCentromer() As Boolean

If the band description describes a centromer (i.e. "p10", "q10", or "cen"), returns true.

Return Value

  • true, if the band describes a centromere.
  • false, otherwise.

Remarks

  • a centromere is detected by its description as "cen", "p10", or "q10".

Example

  • With band 13q22, isCentromer returns "false".
  • With band 13p10, isCentromer returns "true".

    • Public Function isCloserToPTerThan(ByRef CompareBand As Band) As Boolean

    Determines whether the band is closer to the p-terminus than the CompareBand. Both bands must reside on the same chromosome, else an exception will be thrown.

    Note: The return value is not very consistent when both bands are equal. In such a case, the compareTo function is recommended.

    Return Value

    • true, if this band was found closer to the p terminus than CompareBand.
    • false, otherwise.

    Parameter

    • CompareBand: a reference to a band object this instance is to be compared with.

    Exception

    • If this band and CompareBand do not belong to the same chromosome, an exception is thrown.

    Remarks

    • also returns true, if for at least one of the bands only the chromosome is known.

    Example

    • If band 13q22 is compared to band 13q23, isCloserToPTerThan returns true.
    • If band 13q22 is compared to band 13p13, isCloserToPTerThan returns false.

    Public Function isCloserToPTerThan(ByRef CompareBand As Band, ByVal MayContainUncertainties As Boolean) As Boolean

    Determines whether the band is closer to the p-terminus than the CompareBand. Both bands must reside on the same chromosome, else an error will be raised.

    If MayContainUncertainties is true, analysis will be delegated to the previous isCloserToPTerThan function. Otherwise, a faster algorithm will be used.

    Note: The return value is not very consistent when both bands are equal. In such a case, the compareTo function is recommended.

    Return Value

    • true, if this band was found closer to the p terminus than CompareBand.
    • false, otherwise.

    Parameter

    • CompareBand: a reference to a band object this instance is to be compared with.
    • MayContainUncertainties indicates if at least one of this instance and CompareBand may conatain uncertainties.

    Exception

    • If this band and CompareBand do not belong to the same chromosome, an exception is thrown.

    Remarks

    • If both this instance and CompareBand are known to be free from uncertainties, MayContainUncertainties can be set to false in order to enhance performance.
    • If MayContainUncertainties is true, this function delegates to the above version of isCloserToPTerThan.

    Public Function isMoreDistalThan(ByRef CompareBand As Band) As Boolean

    Determines if this band is farther away from the centromere than CompareBand by comparing the digits of the band numbers. Returns true, if the digits of the band correspond to a band farther away from the centromer than the digits of the CompareBand.

    Return Value

    • true, if this band is farther away from the centromere than CompareBand.
    • false, otherwise.

    Exception

    • If this band and CompareBand do not belong to the same chromosome, an exception is thrown.

    Remarks

    • the designation of the arm is ignored.

    Example

    • If band 13q22 is compared to band 13q23, isMoreDistalThan returns false.
    • If band 13q22 is compared to band 13q10, isMoreDistalThan returns true.

    Public Function isOnOppositeArm(ByRef CompareBand As Band) As Boolean

    Determines whether the band resides on the opposite arm of the chromosome than CompareBand by comparing the description of their arms without uncertainties.

    Return Value

    • true, if this band and CompareBand reside on different arms of the chromosome.
    • false, otherwise.

    Exception

    • If this band and CompareBand do not belong to the same chromosome, an exception is thrown.

    Remarks

    • Comparison is performed on the description of the arms without uncertainties.

    Example

    • If band 13q22 is compared to band 13q23, isOnOppositeArm returns false.
    • If band 13q22 is compared to band 13p12, isOnOppositeArm returns true.
    • If band 13q22 is compared to band 13?, isOnOppositeArm returns true.

    Public Function isRegion() As Boolean

    Returns true if the band description describes an interval.

    Return Value

    • true, if teh description describes an interval.
    • false, otherwise.

    Remarks

    • Description of intervals is done using an approximate sign ("~"). A minus ("-") is also accepted instead of the approximate sign.

    Example

    • With band 13q22~32, isRegion returns true.
    • With band 13q22, isRegion returns false.

    Public Function isTerminus() As Boolean

    Determines if this band describes a chromosomal terminus.

    Return Value

    • true, if this band describes a terminus.
    • false, otherwise.

    Remarks

    • a terminus is decribed with the symbol "ter".
    • a terminal band which is described with its band number but not with "ter", is not recognozed as a terminus

    Example

    • With band 13q22~32, isTerminus returns false.
    • With band 13qter, isTerminus returns true.

    Public Shadows Function toString() As String

    The full description of the band including chromosome, arm, and band number (if present). May show question marks and interval signs.
    Actually it returns the value of the "Band" property.

    Public Shadows Function toString(format as String) As String

    Returns a textual description of the band including chromosome, arm, band number, and uncertainties (if present).

    Return Value

    • a textual description of the band.

    Parameter

    • format: a short description of the format.

      • The following values are defined:
      • "S": standard (lenient) description. Makes use of the original description.
      • "E": exact description. All items are recalculated with strict adherence to the ISCN manual.
      • "EX": exact description without chromosome number. Corresponds to "E", but does not show the chromosome number; this option is used for aberration descriptions in the ISCN which require a separation of chromosomes from their bands.

    Remarks

    • If the format is unknown, "S" formatting will be used by default.
    • This function allows the removal of small errors from a formula.

    Example

    • The input "9q.34?1" will be transformed by "toString("E")" to "9q34.?1", by "toString("EX")" to "q34.?1".

    Interaction with other classes

    Classes using Band

    The Band class is a very fundamental class in the CyDAS project. It is used directly or indirectly by almost every class of the package.

    Band objects are components of the Fragment class (two Band objects per Fragment object), the QualitativeAberration class (one Band object per QualitativeAberration object), the QuantitativeAberration class (2 Band objects per QuantitativeAberration object), the Fusion class (2 Band objects per Fusion object), the GainLossStruct class (1 Band object per GainLossStruct object) and the Bands class (0, 1 or many Band objects per Bands object).

    Transient use of the Band class occurs in the Aberration class, the Chromosome class and the CyDASGraphics class.

    Classes used by Band

    The band class itself does not contain other classes of the CyDAS package as an integral component. A bands object is used temporarily in one function as a return value.

    Resources used by Band

    It is the band class to read the resource file "Chromosome.xml" containing the description of the bands of the normal karyotype. Other classes requiring such information get it via the Band class.