BasicLocationTable of Contents

Basic Location Object Introduction Public Methods Attach AugmentString Begin Cmp Contig Dir EndPoint FixContig IfValid Index Length Matches Merge new Overlap Parent Parse SeedString String Virtual Methods Adjacent Combine Compare Index Left Lengthen NumDirection Peel PointOffset Reverse Right SetBegin SetEnd Split Truncate Upstream Widen Forward Basic Location Object Introduction Override Methods Adjacent Combine Compare Left Lengthen NumDirection Peel PointOffset Reverse Right SetBegin SetEnd Split Truncate Upstream Widen Backward Basic BasicLocation Object Introduction Override Methods Adjacent Combine Compare Index Left Lengthen NumDirection Peel PointOffset Reverse Right SetBegin SetEnd Split Truncate Upstream Widen Basic Location Object IntroductionA basic location defines a region of a contig. Because of the way genetic feature work, a basic location has a direction associated with it. The traditional method for encodin a basic location is to specify the contig ID, the starting offset, and the ending offset. If th start is before the end, we have a forward basic location, and if the start is after the end, w have a backward basic location.

RED_1_400is the first 400 nucleotides of the RED contig, processed forward.

NC_000913_500_401is a 100-nucleotide region in NC_000913 that is processed backward from the 500th nucleotide.

Note that even though they are called "offsets", location indices are 1-based Note also that the possibility of an underscore in the contig ID makes the parsing a littl tricky.

The Sprout uses a slightly different format designed to allow for the possibility of zero-length regions. Instead of a starting and ending position, we specify the start position the direction (+ or -), and the length. The Sprout versions of the two example location above are RED_1+400 (corresponds to RED_1_400), and NC_000913_500-100 (correspond to NC_000913_500_401).

Working with the raw location string is difficult because it can have one of two format and it is constantly necessary to ask if the location is forward or backward. The basic locatio object seeks to resolve these differences by providing a single interface that can b used regardless of the format or direction.

It is frequently useful to keep additional data about a basic location while it is being passe around. The basic location object is a PERL hash, and this additional data is kept in the objec by adding hash keys. The internal values used by the object have keys preceded by a underscore, so any keys not beginning with underscores are considered to be additiona values. The additional values are called augments.

When a basic location is in its string form, the augments can be tacked on using parenthese enclosing a comma-delimited list of assignments. For example, say we want to describ the first 400 base pairs in the contig RED, and include the fact that it is the secon segment of feature fig|12345.1.peg.2. We could use the key fid for the feature ID an idx for the segment index (0-based), in which case the location string would be

When this location string is converted to a location object in the variable $loc, w would have

$loc->{fig} eq 'fig|12345.1.peg.2'$loc->{idx} == 1Spaces can be added for readability. The above augmented location string can also b coded as

A basic location is frequently part of a full location. Full locations are described by th FullLocation object. A full location is a list of basic locations associated with a genom and a FIG-like object. If the parent full location is known, we can access the basic location' raw DNA. To construct a basic location that is part of a full location, we add the parent ful location and the basic location's index to the constructor. In the constructor below $parent points to the parent full location.

my $secondLocation = BasicLocation->new("RED_450+100", $parent, 1);Public Methods newmy $loc = BasicLocation->new($locString, $parentLocation, $idx);

Construct a basic location from a location string. A location string has the form contigID_begindirlen where begin is the starting position dir is + for a forward transcription or - for a backward transcription and len is the length. So, for example, 1999.1_NC123_4000+200 describes a location beginning at position 4000 of contig 1999.1_NC123 and ending at position 4199. Similarly, 1999.1_NC123_2000-400 describes a location in the same contig starting at position 2000 and ending at position 1601.

Augments can be specified as part of the location string using parentheses an a comma-delimited list of assignments. For example, the following constructo creates a location augmented by a feature ID called fid and an index valu called idx.

my $loc = BasicLocation->new("NC_000913_499_400(fid = fig|83333.1.peg.10, idx => 2)");All fields internal to the location object have names beginning with a underscore (_), so as long as the value name begins with a letter there should be no conflict.

locStringLocation string, as described above.

parentLocation (optional)Full location that this basic location is part of (if any).

idx (optional)Index of this basic location in the parent full location.

my $loc = BasicLocation->new($location, $contigID);

Construct a location by copying another location and plugging in a new contig ID.

locationLocation whose data is to be copied.

contigID (optional)ID of the new contig to be plugged in.

my $loc = BasicLocation->new($contigID, $beg, $dir, $len, $augments, $parentLocation, $idx);

Construct a location from specific data elements, in particular the contig ID, the startin offset, the direction, and the length.

contigIDID of the contig on which the location occurs.

begStarting offset of the location.

dirDirection of the location: + for a forward location and - for a backward location. I _ is specified instead, it will be presumed that the fourth argument is an endpoint and no a length.

lenLength of the location. If the direction is an underscore (_), it will be the endpoin instead of the length.

augments (optional)Reference to a hash containing any augment values for the location.

parentLocation (optional)Full location that this basic location is part of (if any).

idx (optional)Index of this basic location in the parent full location.

Contigmy $contigID = $loc->Contig;

Return the location's contig ID.

Beginmy $beg = $loc->Begin;

Return the location's starting offset.

Dirmy $dirChar = $loc->Dir;

Return the location's direction: + for a forward location and - for a backward one.

Lengthmy $len = $loc->Length;

Return the location's length (in nucleotides).

EndPointmy $offset = $loc->EndPoint;

Return the location's ending offset.

Parentmy $parentLocation = $loc->Parent;

Return the full location containing this basic location (if any).

Indexmy $idx = $loc->Index;

Return the index of this basic location inside the parent location (if any).

Stringmy $string = $loc->String;

Return a Sprout-format string representation of this location.

SeedStringmy $string = $loc->SeedString;

Return a SEED-format string representation of this location.

AugmentStringmy $string = $loc->AugmentString;

Return a Sprout-format string representation of this location with augment dat included. The augment data will be appended as a comma-delimited list of assignment enclosed in parentheses, the exact format expected by the single-argument location objec constructor new.

IfValidmy $distance = IfValid($distance);

Return a distance if it is a valid offset inside this location, and an undefined value otherwise.

distanceRelevant distance inside this location.

RETURNReturns the incoming distance if it is non-negative and less than the location length, and a undefined value otherwise.

Cmpmy $compare = BasicLocation::Cmp($a, $b);

Compare two locations.

The ordering principle for locations is that they are sorted first by contig ID, then b leftmost position, in reverse order by length, and then by direction. The effect is tha within a contig, the locations are ordered first and foremost in the way they woul appear when displayed in a picture of the contig and second in such a way that embedde locations come after the locations in which they are embedded. In the case of tw locations that represent the exact same base pairs, the forward (+) location i arbitrarily placed first.

aFirst location to compare.

bSecond location to compare.

RETURNReturns a negative number if the a location sorts first, a positive number if th b location sorts first, and zero if the two locations are the same.

Matchesmy $flag = BasicLocation::Matches($locA, $locB);

Return TRUE if the two locations contain the same data, else FALSE. Augment data is include in the comparison.

locA, locBLocations to compare.

RETURNReturns TRUE if the two locations contain the same data, else FALSE.

Attachmy = $loc->Attach($parent, $idx);

Point this basic location to a parent full location. The basic location will not b inserted into the full location's data structures.

parentParent full location to which this location should be attached.

idxIndex of this location in the full location.

FixContig$loc->FixContig($genomeID);

Insure the genome ID is included in the Contig string. Some portions of the syste store the contig ID in the form genome:contig, while some use only the contig ID If this location's contig ID includes a genome ID, nothing will happen, but if it doe note, the caller-specified genome ID will be prefixed to the contig string.

genomeIDID of the genome for this location's contig.

Parsemy ($contig, $beg, $end) = BasicLocation::Parse($locString);

Parse a location string and return the contig ID, start position, and end position.

locStringLocation string to parse. It may be either Sprout-style or SEED-style.

RETURNReturns the contig ID, start position, and end position as a three-element list.

Overlapmy $len = $loc->Overlap($b,$e);

Determine how many positions in this location overlap the specified region. The region is define by its leftmost and rightmost positions.

bLeftmost position in the region to check.

eRightmost position in the region to check.

RETURNReturns the number of overlapping positions, or 0 if there is no overlap.

Merge$loc->Merge($loc2);

Merge another location into this one. The result will include all bases in bot locations and will have the same direction as this location. It is assumed bot locations share the same contig.

loc2Location to merge into this one.

Virtual MethodsThese methods are implemented by the subclasses. They are included here for documentatio purposes.

Leftmy $leftPoint = $loc->Left;

Return the offset of the leftmost point of the location.

Rightmy $rightPoint = $loc->Right;

Return the offset of the rightmost point of the location.

Comparemy ($distance, $cmp) = $loc->Compare($point);

Determine the relative location of the specified point on the contig. Returns a distance which indicates the location relative to the leftmost point of the contig, and a compariso number, which is negative if the point is to the left of the location, zero if the point i inside the location, and positive if the point is to the right of the location.

Splitmy $newLocation = $loc->Split($offset);

Split this location into two smaller ones at the specified offset from the left endpoint. Th new location split off of it will be returned.

offsetOffset into the location from the left endpoint of the point at which it should be split.

RETURNThe new location split off of this one.

Reverse$loc->Reverse;

Change the polarity of the location. The location will have the same nucleotide range, bu the direction will be changed.

Indexmy $index = $loc->Index($point);

Return the index of the specified point in this location. The value returned is the distanc from the beginning. If the specified point is not in the location, an undefined value is returned.

pointOffset into the contig of the point in question.

RETURNReturns the distance of the point from the beginning of the location, or an undefined value if th point is outside the location.

PointOffsetmy $offset = $loc->PointOffset($index);

Return the offset into the contig of the point at the specified position in the location. A positio of 0 will return the beginning point, a position of 1 returns the point next to that, and a positio 1 less than the length will return the ending point.

indexIndex into the location of the relevant point.

RETURNReturns an offset into the contig of the specified point in the location.

Peelmy $peel = $loc->Peel($length);

Peel a specified number of positions off the beginning of the location. Peeling split a location at a specified offset from the beginning, while splitting takes it at specified offset from the left point. If the specified length is equal to or longe than the location's length, an undefined value will be returned.

lengthNumber of positions to split from the location.

RETURNReturns a new location formed by splitting positions off of the existing location, which i shortened accordingly. If the specified length is longer than the location's length, a undefined value is returned and the location is not modified.

SetBegin$loc->SetBegin($newBegin);

Change the begin point of this location without changing the endpoint.

newBeginProposed new beginning point.

SetEnd$loc->SetEnd($newEnd);

Change the endpoint of this location without changing the begin point.

newEndProposed new ending point.

Widenmy = $loc->Widen($distance, $max);

Add the specified distance to each end of the location, taking care not t extend past either end of the contig. The contig length must be provide to insure we don't fall off the far end; otherwise, only the leftwar expansion is limited.

distanceNumber of positions to add to both ends of the location.

max (optional)Maximum possible value for the right end of the location.

Lengthenmy = $loc->Lengthen($distance, $max);

Add the specified distance to the end of the location, taking care not t extend past either end of the contig. The contig length must be provide to insure we don't fall off the far end; otherwise, only the leftwar expansion is limited.

distanceNumber of positions to add to the end of the location.

max (optional)Maximum possible value for the right end of the location.

Upstreammy $newLoc = $loc->Upstream($distance, $max);

Return a new location upstream of the given location, taking care not t extend past either end of the contig.

distanceNumber of positions to add to the front (upstream) of the location.

max (optional)Maximum possible value for the right end of the location.

RETURNReturns a new location object whose last position is next to the firs position of this location.

Truncate$loc->Truncate($len);

Truncate the location to a new length. If the length is larger than the location length, the the location is not changed.

lenProposed new length for the location.

Adjacentmy $okFlag = $loc->Adjacent($other);

Return TRUE if the other location is adjacent to this one, else FALSE. The othe location must have the same direction and start immediately after this location' endpoint.

otherBasicLocation object for the other location.

RETURNReturns TRUE if the other location is an extension of this one, else FALSE.

Combine$loc->Combine($other);

Combine another location with this one. The result will contain all bases in bot original locations. Both locations must have the same contig ID and direction.

otherOther location to combine with this one.

NumDirectionmy $multiplier = $loc->NumDirection();

Return 1 if this is a forward location, -1 if it is a backward location.

Forward Basic Location Object IntroductionA forward location object is a location in a contig that is transcribed from left to right It is a subclass of the BasicLocation object, and contains methods that require differen implementation for a forward location than a backward location.

Override Methods Leftmy $leftPoint = $loc->Left;

Return the offset of the leftmost point of the location.

Rightmy $rightPoint = $loc->Right;

Return the offset of the rightmost point of the location.

Comparemy ($distance, $cmp) = $loc->Compare($point);

Splitmy $newLocation = $loc->Split($offset);

Split this location into two smaller ones at the specified offset from the left endpoint. Th new location split off of it will be returned. If the offset is at either end of the location no split will occur and an underfined value will be returned.

offsetOffset into the location from the left endpoint of the point at which it should be split.

RETURNThe new location split off of this one, or an undefined value if no split was necessary.

Peelmy $peel = $loc->Peel($length);

lengthNumber of positions to split from the location.

Reverse$loc->Reverse;

Change the polarity of the location. The location will have the same nucleotide range, bu the direction will be changed.

pointOffset into the contig of the point in question.

RETURNReturns the distance of the point from the beginning of the location, or an undefined value if th point is outside the location.

PointOffsetmy $offset = $loc->PointOffset($index);

indexIndex into the location of the relevant point.

RETURNReturns an offset into the contig of the specified point in the location.

SetBegin$loc->SetBegin($newBegin);

Change the begin point of this location without changing the endpoint.

newBeginProposed new beginning point.

SetEnd$loc->SetEnd($newEnd);

Change the endpoint of this location without changing the begin point.

newEndProposed new ending point.

Widenmy = $loc->Widen($distance, $max);

distanceNumber of positions to add to both ends of the location.

max (optional)Maximum possible value for the right end of the location.

Lengthenmy = $loc->Lengthen($distance, $max);

distanceNumber of positions to add to the end of the location.

max (optional)Maximum possible value for the right end of the location.

Upstreammy $newLoc = $loc->Upstream($distance, $max);

Return a new location upstream of the given location, taking care not t extend past either end of the contig.

distanceNumber of positions to add to the front (upstream) of the location.

max (optional)Maximum possible value for the right end of the location.

RETURNReturns a new location object whose last position is next to the firs position of this location.

Truncate$loc->Truncate($len);

Truncate the location to a new length. If the length is larger than the location length, the the location is not changed.

lenProposed new length for the location.

Adjacentmy $okFlag = $loc->Adjacent($other);

Return TRUE if the other location is adjacent to this one, else FALSE. The othe location must have the same direction and start immediately after this location' endpoint.

otherBasicLocation object for the other location.

RETURNReturns TRUE if the other location is an extension of this one, else FALSE.

Combine$loc->Combine($other);

Combine another location with this one. The result will contain all bases in bot original locations. Both locations must have the same contig ID and direction.

otherOther location to combine with this one.

NumDirectionmy $multiplier = $loc->NumDirection();

Return 1 if this is a forward location, -1 if it is a backward location.

Backward Basic BasicLocation Object IntroductionA backward location object is a location in a contig that is transcribed from right to left It is a subclass of the BasicLocation object, and contains methods that require differen implementation for a forward location than a backward location.

Override Methods Leftmy $leftPoint = $loc->Left;

Return the offset of the leftmost point of the location.

Rightmy $rightPoint = $loc->Right;

Return the offset of the rightmost point of the location.

Comparemy ($distance, $cmp) = $loc->Compare($point);

Splitmy $newLocation = $loc->Split($offset);

offsetOffset into the location from the left endpoint of the point at which it should be split.

RETURNThe new location split off of this one, or an undefined value if no split was necessary.

Peelmy $peel = $loc->Peel($length);

lengthNumber of positions to split from the location.

Reverse$loc->Reverse;

Change the polarity of the location. The location will have the same nucleotide range, bu the direction will be changed.

Indexmy $index = $loc->Index($point);

Return the index of the specified point in this location. The value returned is the distanc from the beginning. If the specified point is not in the location, an undefined value is returned.

pointOffset into the contig of the point in question.

RETURNReturns the distance of the point from the beginning of the location, or an undefined value if th point is outside the location.

PointOffsetmy $offset = $loc->PointOffset($index);

indexIndex into the location of the relevant point.

RETURNReturns an offset into the contig of the specified point in the location.

SetBegin$loc->SetBegin($newBegin);

Change the begin point of this location without changing the endpoint.

newBeginProposed new beginning point.

SetEnd$loc->SetEnd($newEnd);

Change the endpoint of this location without changing the begin point.

newEndProposed new ending point.

Widenmy = $loc->Widen($distance, $max);

distanceNumber of positions to add to both ends of the location.

max (optional)Maximum possible value for the right end of the location.

Upstreammy $newLoc = $loc->Upstream($distance, $max);

Return a new location upstream of the given location, taking care not t extend past either end of the contig.

distanceNumber of positions to add to the front (upstream) of the location.

max (optional)Maximum possible value for the right end of the location.

RETURNReturns a new location object whose last position is next to the firs position of this location.

Truncate$loc->Truncate($len);

Truncate the location to a new length. If the length is larger than the location length, the the location is not changed.

lenProposed new length for the location.

Adjacentmy $okFlag = $loc->Adjacent($other);

Return TRUE if the other location is adjacent to this one, else FALSE. The othe location must have the same direction and start immediately after this location' endpoint.

otherBasicLocation object for the other location.

RETURNReturns TRUE if the other location is an extension of this one, else FALSE.

Combine$loc->Combine($other);

Combine another location with this one. The result will contain all bases in bot original locations. Both locations must have the same contig ID and direction.

otherOther location to combine with this one.

NumDirectionmy $multiplier = $loc->NumDirection();

Return 1 if this is a forward location, -1 if it is a backward location.

Lengthenmy = $loc->Lengthen($distance, $max);

distanceNumber of positions to add to the end of the location.

max (optional)Maximum possible value for the right end of the location.