Skip to content

Latest commit

 

History

History
657 lines (488 loc) · 34.2 KB

chromRegion.md

File metadata and controls

657 lines (488 loc) · 34.2 KB

ChromRegion

A JS class representing chromosomal regions with several basic operations.

License: Copyright 2017-2019 The Regents of the University of California. All Rights Reserved.

Created by Xiaoyi Cao, Department of Bioengineering

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

ChromRegion ⏏

Data structure for chromosomal region.

Kind: Exported class

new ChromRegion(mainParams, [chromInfo], [additionalParams], [zeroBased])

Param Type Description
mainParams string | ChromRegion | ChromRegionLikeObj | ObjectWithBed Main parameters used in the ChromRegion. Four types of input is supported: * A string like chr1:12345-56789, strands can be specified like chr1:12345-56789(-); * An object with bedString (BED3+ format string) as one property; * An object with chr, start, end (required), and strand (optional) or other essential properties; * A ChromRegion instance. In this case the behavior will be similar to a copy constructor (all additional properties will be copied).
[chromInfo] ChromInfoCollection The collection of chromosomal information for the reference genome of the region, used for clipping the region, use falsy values to omit.
[additionalParams] Object Additional parameters to be added to this.
[zeroBased] boolean Whether the given chrom region's coordinate is zero based. Note: Internal storage of the chrom region is always 0-based by default. To change this, override CHROM_BASE to 1.

chromRegion.length : number

Length of the chromosomal region

Kind: instance property of ChromRegion
Read only: true

chromRegion.startCoor : CoordinateObj

An object with the chromosomal name and starting coordinate.

Kind: instance property of ChromRegion
Read only: true

chromRegion.endCoor : CoordinateObj

An object with the chromosomal name and ending coordinate (included).

Kind: instance property of ChromRegion
Read only: true

chromRegion.start : number

Starting coordinate. Setting to invalid values will cause an exception to be thrown. Note that this value should be the first 0-based coordinate within the region (inclusive). It will be one smaller than the starting value in the 'chrX:XXXXX-XXXXX' annotation as the annotation is 1-based inclusive.

Kind: instance property of ChromRegion

chromRegion.end : number

Ending coordinate. Setting to invalid values will cause an exception to be thrown. Note that this value should be the first 0-based coordinate after the region (exclusive). This will be the same end value in the 'chrX:XXXXX-XXXXX' annotation as the annotation is 1-based inclusive. If this.end === this.start, the length of the region is 0.

Kind: instance property of ChromRegion

chromRegion.strand : boolean | null

Strand information, null for unknown or not applicable.

Kind: instance property of ChromRegion

chromRegion.shortName : string

The possibly shortened name of this.

The name shortening rule:

  • If length of this.name is not greater than this.constructor._REGION_SHORTNAME_LIMIT, no shortening happens;
  • If length of this.name is greater than this.constructor._REGION_SHORTNAME_LIMIT, it will be shortened by taking only the front substring with a length of this.constructor._REGION_SHORTNAME_PREFIX_LENGTH, adding ellipsis ('...'), then taking the ending substring with a length of this.constructor._REGION_SHORTNAME_SUFFIX_LENGTH

For example, suppose all values are at their default, then:

  • 'Region1' will become 'Region1';
  • 'Superlongregion123' will become 'Superl...n123'

Kind: instance property of ChromRegion
Read only: true

chromRegion._mergeParameters(paramObject) ⇒ ChromRegion

Merge the properties of a parameter object into this. If this already has a property with the same name (or cannot be assigned for any reason), it will be ignored.

Kind: instance method of ChromRegion
Returns: ChromRegion - Returns this
Access: protected

Param Type Description
paramObject Object The parameter object

chromRegion.clipRegion([chromInfo], [minLength]) ⇒ ChromRegion

Clip the chromosomal region.

All coordinates less than this.constructor.CHROM_BASE will be clipped to this.constructor.CHROM_BASE.

If the chromosomal information collection (from a reference) is provided, the chromosomal region will be clipped according to the matching chromosomal information in the collection. For example, in reference GRCh38, chromosome 1 has a range of [1, 248956422], then a ChromRegion chr1:100-300000000 will be clipped to chr1:100-248956422 after calling this function.

The function can also provide a minimum chromosomal length, if the clipped region's length is less than the minimal length, it will be extended accordingly to try to match the minimum chromosomal length.

Kind: instance method of ChromRegion
Returns: ChromRegion - this

Param Type Description
[chromInfo] ChromInfoCollection The collection of chromosomal information.
[minLength] number the minimum chromosomal length

chromRegion._regionFromString(regionString, [chromInfo], [additionalParams], [zeroBased]) ⇒ ChromRegion

Convert the region string chrX:XXXX-XXXX to this

Kind: instance method of ChromRegion
Returns: ChromRegion - this
Access: protected

Param Type Description
regionString string The string to be converted from
[chromInfo] ChromInfoCollection The collection of chromosomal information (used to clip this).
[additionalParams] Object Additional parameters to be added to this.
[zeroBased] boolean Whether the string is zero-based

chromRegion._regionFromObject(regionObject, [additionalParams]) ⇒ ChromRegion

Convert an object with chr, start, end and (optional) strand properties to this

Kind: instance method of ChromRegion
Returns: ChromRegion - this
Access: protected

Param Type Description
regionObject ChromRegionLikeObj | ObjectWithBed | ChromRegion The object to be converted from
[additionalParams] Object Additional parameters to be added to this.

chromRegion._regionFromBed(bedString) ⇒ ChromRegion

Convert the BED format string chrX XXXX XXXX to this. Note that only the 1st-3rd fields (BED3), the 4th field (if exists), and the 6th field (if exists) are used. BED coordinates are always 0-based, inclusive for start and exclusive for end.

Kind: instance method of ChromRegion
Returns: ChromRegion - this
Access: protected

Param Type Description
bedString string The BED string to be converted from

chromRegion.regionToString([includeStrand]) ⇒ string

Convert this to a human-readable string. <chromosome name>:<start>-<end>(<strand>)

Note: Both values will be 1-based inclusive.

Kind: instance method of ChromRegion

Param Type Default Description
[includeStrand] boolean true Whether to include strand information at the end. If this does not have strand information, this flag has no effect. Note: Default value is true.

chromRegion.regionToBed([includeStrand]) ⇒ string

Convert this to a BED4/BED6 string

Kind: instance method of ChromRegion

Param Type Default Description
[includeStrand] boolean true Whether to include strand information at the end. If true (default), a BED6 string will be returned with strand field being +, - or . and score field being 0. Note: Default value is true.

chromRegion.toString() ⇒ string

Convert this to a human-readable string with strand information.

Kind: instance method of ChromRegion

chromRegion.getStrand(flankbefore, flankafter) ⇒ string

Strand information in string, padded with flanking strings.

Kind: instance method of ChromRegion

Param Type Description
flankbefore string Flanking string before the result, for example: '('
flankafter string Flanking string after the result, for example: ')'

chromRegion.overlap(region, [strandSpecific]) ⇒ number

Return the length of overlap between this and any given region.

Kind: instance method of ChromRegion

Param Type Description
region ChromRegion The region to be overlapped with.
[strandSpecific] boolean Whether this overlap should be strand- specific. If true, regions with different strands will not be considered as overlapping. NOTE: Regions without strands will not be affected. Consider strand === null as a wildcard that matches any strand. This applies to this.overlap, this.assimilate, this.concat, this.intersect and this.getMinus

chromRegion.overlaps(region, [strandSpecific]) ⇒ number

Deprecated

Return the length of overlap between this and any given region. Deprecated, please use this.overlap instead.

Kind: instance method of ChromRegion

Param Type Description
region ChromRegion The region to be overlapped with.
[strandSpecific] boolean Whether this overlap should be strand- specific. If true, regions with different strands will not be considered as overlapping.

chromRegion.assimilate(region, [strandSpecific], [ignoreOverlap]) ⇒ ChromRegion | null

Assimilate region if this overlap with it by expanding this to cover the entire region.

If this does not overlap with region, return null (this will not be changed in this case).

Kind: instance method of ChromRegion

Param Type Description
region ChromRegion The region to be assimilated.
[strandSpecific] boolean Whether the assimilation is strand-specific.
[ignoreOverlap] boolean If true, the region to be assimilated does not need to be overlapping with this (it still needs to be at the same chromosome, though).

chromRegion.concat(region, [strandSpecific]) ⇒ ChromRegion | null

Concatenate this with region. Concat happens only when the two regions are adjacent to, but not overlapping with each other. region can be at the either end of this.

Return this if concatenation happens, null otherwise (where this will not be changed).

Kind: instance method of ChromRegion

Param Type Description
region ChromRegion The region to be concatenated
[strandSpecific] boolean Whether the concatenation is strand-specific

chromRegion.intersect(region, [strandSpecific]) ⇒ ChromRegion | null

Intersect this with region by removing non-overlapping parts.

If this does not overlap with region, return null (this will not be changed in this case).

Kind: instance method of ChromRegion

Param Type Description
region ChromRegion The region to be overlapped
[strandSpecific] boolean Whether the intersection is strand-specific

chromRegion.getMinus(region, [strandSpecific]) ⇒ Array.<ChromRegion>

Get the subtraction region from this by removing overlapping parts. The resulting one or two ChromRegion part will be returned in an array. this will not be changed in this operation.

If this does not overlap with region (or strandSpecific === true and the strands are different), return [this.clone()]; if this is entirely covered with region, return [].

Regions with a length of 0 can be used as "dividers" to divide this into two consecutive parts.

Kind: instance method of ChromRegion
Returns: Array.<ChromRegion> - Subtracted region(s), ordered.

Param Type Description
region ChromRegion The region to be subtracted from this.
[strandSpecific] boolean Whether the intersection is strand-specific.

chromRegion.move(distance, [isProportion], [chromInfo], [relativeToStrand]) ⇒ ChromRegion

Move this by distance given. Use a negative value to move to the left-hand side and a positive value to move to the right-hand side.

Kind: instance method of ChromRegion

Param Type Description
distance number The distance to be moved
[isProportion] boolean Whether distance is given as an absolute bp value or a proportion (of this.length).
[chromInfo] ChromInfoCollection The collection of chromosomal information for clipping purposes.
[relativeToStrand] boolean Whether the direction of distance is relative to this.strand. Will only be honored if this.strand is not null.

chromRegion.clone() ⇒ ChromRegion

Returns a clone of this, all additional properties will be shallow-copied.

Kind: instance method of ChromRegion

chromRegion.getShift(distance, [isProportion], [chromInfo], [relativeToStrand]) ⇒ ChromRegion

Get a copy of this with shifted location (this will not change). See this.move for parameter details.

Kind: instance method of ChromRegion

Param Type Description
distance number The shift distance.
[isProportion] boolean Whether distance is given as an absolute bp value or a proportion (of this.length).
[chromInfo] ChromInfoCollection The collection of chromosomal information for clipping purposes.
[relativeToStrand] boolean Whether the direction of distance is relative to this.strand. Will only be honored if this.strand is not null.

chromRegion.extend(sizeDiff, [center], [isProportion], [chromInfo], [minimumSize]) ⇒ ChromRegion

Extend / Shrink this

Kind: instance method of ChromRegion

Param Type Description
sizeDiff number The difference to be extended / shrunk. Use a positive value to extend and a negative value to shrink.
[center] number The center point for the extension / shrinkage. Difference in sizes (additional bases after extension / removed bases after shrinkage) will be allocated proportionally to the length of this separated by center. Default value is the center of this, so that additional bases will be equally distributed to both ends and removed bases will be equally taken from both ends. If center is at this.start, then all extended bases will be put at the end and all removed bases will be taken from the end. If center is outside this, it will be moved to the closest point on this.
[isProportion] boolean Whether sizeDiff is an absolute bp value or a proportion of this.length.
[chromInfo] ChromInfoCollection The collection of chromosomal information for clipping purposes.
[minimumSize] number The minimum size of the resulting ChromRegion object.

chromRegion.getExtension(sizeDiff, [center], [isProportion], [chromInfo], [minimumSize]) ⇒ ChromRegion

Get an extended / shrunk copy of this. this will not be changed. See this.extend for parameter details.

Kind: instance method of ChromRegion

Param Type Description
sizeDiff number The difference to be extended / shrunk. Use a positive value to extend and a negative value to shrink.
[center] number The center point for the extension / shrinkage.
[isProportion] boolean Whether sizeDiff is an absolute bp value or a proportion of this.length.
[chromInfo] ChromInfoCollection The collection of chromosomal information for clipping purposes.
[minimumSize] number The minimum size of the resulting ChromRegion object.

chromRegion.equalTo([chrRegion]) ⇒ boolean

Whether this region equals to the given region. (Only chr, start, end, strand and name are compared.)

Extensions of this class shall define their own equalTo function (or the static isEqual function).

Kind: instance method of ChromRegion

Param Type Description
[chrRegion] ChromRegion region to be compared with

ChromRegion.clipCoordinate(coor, [chromInfo]) ⇒ CoordinateObj

Helper function to clip a coordinate object (see this.startCoor or this.endCoor) with a collection of chromInfo.

Kind: static method of ChromRegion

Param Type Description
coor CoordinateObj Coordinate object
[chromInfo] ChromInfoCollection The collection of chromosomal information.

ChromRegion.isValidChromRegion(chrRegion, [chromInfo]) ⇒ boolean

Validate whether the region is a valid region.

Kind: static method of ChromRegion

Param Type Description
chrRegion ChromRegion | string The region to be validated
[chromInfo] ChromInfoCollection The reference object

ChromRegion._splitChromNamePart(name) ⇒ Array.<(string|number)>

Split chromosome name into three parts:

  1. Chr (if exists)
  2. Chromosome number (if exists), will be converted to number
  3. The rest of the name

Kind: static method of ChromRegion

Param Type Description
name string Chromosome name to be splited

ChromRegion._compareChromNames(name1, name2)

Compare chromosome names in a more natural way, so that chr10 should be larger than chr2 (not the lexicographical order)

Kind: static method of ChromRegion

Param Type Description
name1 string Name of the first chromosome name
name2 string Name of the second chromosome name

ChromRegion.compare(region1, region2) ⇒ number

Compare two ChromRegions

Whether region1 is considered "smaller than" (to the left-hand side of), equal to, or "larger than" (to the right-hand side of) region2 is determined by the following criteria:

  • If region1.chr has a lower 'natural' order (see this._compareChromNames) than region2.chr, it is considered smaller, otherwise:
  • If region1.chr === region2.chr, but region1.start is smaller than region2.start, it is considered smaller, otherwise:
  • If region1.chr === region2.chr and region1.start === region2.start, but region1.end is smaller than region2.end, it is considered smaller, otherwise:
  • If region1.chr === region2.chr, region1.start === region2.start, and region1.end === region2.end, but region1.strand is smaller than region2.strand (true is smaller than false, which is smaller than null), it is considered smaller, otherwise:
  • If region1.chr === region2.chr, region1.start === region2.start, region1.end === region2.end, and region1.strand === region2.strand, but region1.name is smaller than region2.name (Falsy values are equal to each other and larger than any truthy values. Truthy values are compared lexicographically), it is considered smaller, otherwise:
  • If region1.chr === region2.chr and region1.start === region2.start, but region1.end is smaller than region2.end, it is considered smaller, otherwise:
  • If chr, start, end, strand, and name of region1 and region2 are equal, region1 is considered equal to region2, otherwise region1 is considered larger than region2.

NOTE: strand or name is not taken into consideration in this case.

Kind: static method of ChromRegion
Returns: number - 0 if region1 equals to region2, -1 if region1 is smaller than region2, 1 if region1 is larger than region2

Param Type
region1 ChromRegion
region2 ChromRegion

ChromRegion.isEqual([region1], [region2]) ⇒ boolean

Determine whether two regions are equal (chr, start, end, strand and name are equal), null and undefined can be passed as parameters, in which case the function will return true if both regions are falsy.

If name in both regions are falsy, they are considered as equal.

Kind: static method of ChromRegion

Param Type
[region1] ChromRegion
[region2] ChromRegion

ChromRegion._shortenString(str, limit, prefixLength, suffixLength) ⇒ string

Helper function to get a shortened string if it exceeds a given limit.

Kind: static method of ChromRegion
Access: protected

Param Type Description
str string String to be shortened
limit number Limit of string length
prefixLength number Prefix length if shortening happens
suffixLength number Suffix length if shortening happens

ChromRegion~ChromInfo : Object

Basic chromosome information.

Kind: inner typedef of ChromRegion
Properties

Name Type Description
chrRegion ChromRegion The range of the chromosome
[cent] ChromRegion The range of the chromosome centromere

ChromRegion~ChromRegionLikeObj : Object

An object that can be used to initialize ChromRegion

Kind: inner typedef of ChromRegion
Properties

Name Type Description
chr string The name of the chromosome
start number The start of the chromosomal region
end number The end of the chromosomal region
[strand] boolean | null | string The strand of the region, null for unknown or not applicable, strings like '-' are also acceptable.
[regionname] string The name of the region, will take precedence over name
[name] string The name of the region

ChromRegion~ObjectWithBed : Object

An object that can be used to initialize ChromRegion

Kind: inner typedef of ChromRegion
Properties

Name Type Description
bedString string The BED format string

ChromRegion~ChromInfoCollection : Object.<string, ChromInfo>

An dictionary-like object with chromosomal name as keys and ChromInfo type as values.

Kind: inner typedef of ChromRegion

ChromRegion~CoordinateObj : Object

A coordinate object with chromosome name and single coordinate value.

Kind: inner typedef of ChromRegion
Properties

Name Type Description
chr string The chromosome name
coor number The coordinate value