FullLocationTable of Contents

Full Location Object Introduction Public Methods Adjusted Begin Codon Constrain Contig Dir DNA EndPoint Extend ExtremeCodon GetBest GetBounds Locs new NextPoint PrevPoint Search SeedString Translation Internal Methods FindPattern ParseLocations SearchChunk Full Location Object IntroductionA full location object describes a list of basic locations (segments) in particular genome. In addition to an array of basic location objects, it contain a genome ID and a reference to a FIG-like object. The FIG-like object is alway accessed using the variable $fig. This simplifies the process of determining whic FIG methods must be supported in order to make use of this object's features.

The simplest way to create a full location object is by passing in the genome I and a location string. The location string contains a list of basic location separated by commas. These are converted into location objects and assembled int the full location. The full location is considered bounded by the first and las basic locations in the list. This bounded region has a Left, Right, Begin, an Endpoint, just like a basic location. So, for example, with a location list of

the Left and Begin locations are RED_100, while the Right and EndPointRED_430 Similarly, with the location list

the Left and EndPoint locations are BLUE_200, which the Right and BeginBLUE_500.

A location can be converted to a DNA string using the genome ID and data accessibl through the fig-like object. A location also has a translation that represents th protein sequence produced DNA. The translation can be computed from the DNA or can b provided by the client. If it is provided by the client, it will automatically b extended when the boundaries are moved.

Theoretically, a location can contain basic locations on different contigs an pointing in different directions. In practice, this does not occur; therefore the location will be treated as a set of basic locations in a single directio on a single contig. If this is not the case, problems will arise with some o the methods.

Public Methods newmy $loc = FullLocation->new($fig, $genomeID, $locList, $translation);

Construct a new FullLocation object.

figA fig-like object that can be used to get the DNA and translation information.

genomeIDID of the genome containing the location.

locListList of locations. This can be a reference to a list of location strings, comma-delimited list of location strings, or a reference to a list of basi location objects.

translation (optional)Protein string representing the DNA inside the boundaries of the location.

Locsmy $locObject = $loc->Locs->[$idx];

Return a reference to the array of location objects.

Contigmy $contigID = $loc->Contig();

Return the ID of the base contig for this location list. The base contig is th contig used for most of the locations in the list.

Dirmy $dir = $loc->Dir;

Return the base direction for this location list. The base direction is the directio (+ or -) used for most of the locations in the list.

NextPointmy $offset = $loc->NextPoint;

Return the location immediately after the end point of the last location.

PrevPointmy $offset = $loc->PrevPoint;

Return the location immediately before the begin point of the first location.

Beginmy $offset = $loc->Begin;

Return the begin point of the first location.

EndPointmy $offset = $loc->EndPoint;

Return the end point of the last location.

SeedStringmy $string = $loc->SeedString;

Return a comma-delimited list of this object's basic locations, in SEED format.

Adjustedmy $offset = $loc->Adjusted($oldOffset, $distance);

Adjust the specified offset by the specified distance in the direction of thi location. If this is a forward location, the distance is added; if it is a backwar location, the distance is subtracted.

oldOffsetOffset to adjust.

distanceDistance by which to adjust the offset. This value can be negative.

RETURNReturns a new offset formed by moving the specified distance from the original offse in this location's direction.

GetBestmy $bestKey = FullLocation::GetBest(%hash);

Return the key of the hash element with the highest positive numeric value.

hashA hash mapping keys to numbers.

RETURNReturns the key having the highest value. If the hash is empty, or has no non-negativ values, returns undef.

DNAmy $dnaString = $loc->DNA;

Return the complete DNA string for this location.

Codonmy $codon = $loc->Codon($point);

Return the DNA codon at the specified point on this location's contig in thi location's direction.

pointOffset into the contig of the codon.

RETURNReturns a three-letter DNA codon from the specified point.

Translationmy $proteinString = $loc->Translation($code, $fixStart);

Return the protein translation of this location's DNA. The first time translation is requested, it will be cached in the object, and returne unmodified. It is also possible that a translation specified in th constructor exists, in which case it will be returned. Thus, th $code and $fixStart parameters only matter on the first call.

code (optional)Translation code table, in the form of a hash mapping DNA triples to protei letters. If omitted, the standard translation table in FIG.pm will b used.

fixStart (optional)TRUE if the first DNA triple should be given special handling, else FALSE If TRUE, then a value of TTG or GTG in the first position will b translated to M instead of the value specified in the translation code.

RETURNReturns the protein translation for this location.

Constrainmy $constrainedPoint = $loc->Constrain($point);

Change a point location value so that it fits inside the base contig. If the poin location is less than 1, it will be set to 1. If it's greater than the length o the contig, it will be set to the length of the contig.

pointLocation to be constrained.

RETURNReturns the value of the nearest location that is on the base contig of this location.

Searchmy $newPoint = $loc->Search(\@pattern, $point, $dir, $limit);

Search for a DNA codons in the specified direction from the specifie point. The search is limited to the specified number of positions.

The basic strategy here is that we get a chunk of DNA from the base contig i the specified direction, then we look for the codon. The DNA will be take from the same strand used for most of this location.

patternA bar-separated list of DNA codons for which to search. So, for example, t search for a stop codon, specify 'taa|tga|tag'. To search for att specify 'att'.

pointStarting point for the search.

dirDirection for the search, + for downstream and - for upstream.

limit (optional)Size of the data chunk to use while searching. This limits the memor requirement for the process. If omitted, 9000 is used.

RETURNReturns the point at which the pattern was found, or undef if it was not found.

ExtremeCodonmy $loc->ExtremeCodon($dir);

Return the most extreme codon in the specified direction. This is not always the mos extreme location, since the distance to the appropriate edge of the location must b a multiple of 3.

dirfirst to get the codon moving away from the beginning of the location, lastRETURNReturns the edge location of the desired codon. If we are going toward the left, thi is the left point in the codon; if we are going toward the right, this is the righ point in the codon.

Extendmy = $loc->Extend($newBegin, $newEnd, $trimFlag);

Extend this gene to a new begin point and a new end point. If a translation exists it will be updated to match the new locations. The $trimFlag indicates whethe or not it is permissible to shrink the location at either end. If an attempt is mad to shrink and $trimFlag is not specified, then a fatal error will occur.

newBeginProposed new beginning offset.

Proposed new ending offset.

GetBoundsmy ($boundLoc, $loc1, $locN) = $loc->GetBounds;

Analyze this location and return information about its boundaries. This include a location for the bounds, the first location, and the last location. Th bounds essentially define the location as it would be if it were all on a singl contig in the same direction and had no gaps. The first location is the locatio object containing the begin point of the bounds, and the last location is th location object containing the end point of the bounds.

Internal Methods ParseLocationsParse an array into a list of basic location objects. The array can contai basic location objects or location strings. The first parameter must be th full location object being constructed.

This is a static method.

FindPatternLocate the index of a specified pattern in a DNA string.

This is a static method.

dnaDNA string to search.

patternPattern for which to search (see Search).

RETURNReturns the index of the specified pattern, or undef if the pattern is not found.

SearchChunkSearch for a DNA codons in the specified direction from the specifie point. The search is broken into chunks limited to the specified numbe of positions, which must be a multiple of 3.

This is an instance method.

patternA bar-separated list of DNA codons for which to search. So, for example, t search for a stop codon, specify 'taa|tga|tag'. To search for att specify 'att'.

pointStarting point for the search.

dirDirection for the search, + for downstream and - for upstream.

limitMaximum number of positions to search in the given direction.

RETURNReturns the point at which the pattern was found, or undef if it was not found.