funded by

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

Constructors
Interfaces
Enumerations
Properties
Methods
Interaction with other classes

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

Copyrighted but free software under the GNU Public License.
Binaries and source code can be obtained from the Download section.

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

Resolution: the desired resolution level. Valid values are defined in the enumeration ChromosomeData.eResolutionLevel.

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

The function delegates to ChromosomeData.checkBandExistence(Me).

Public Function clone() As Object Implements ICloneable.Clone

Returns a copy of the Band object.

Return Value

A copy of the Band object.

Implements

ICloneable.Clone

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

ArgumentException: is thrown when obj cannot be cast into Band type.

Implements

IComparable.CompareTo

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

Resolution: the desired resolution level. Valid values are defined in the enumeration ChromosomeData.eResolutionLevel.

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

Values for the resolution level are defined in the enumeration ChromosomeData.eResolutionLevel.

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

the function calls ChromosomeData.getColorForChromosome(ChromosomeNumber).

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

Values for PaintStyle are defined in the Enumeration ChromosomeData.ePaintStyle.

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.

"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.