Class | Bio::Locations
In: | lib/bio/location.rb
Parent: | Object

## Description

The Bio::Locations class is a container for Bio::Location objects: creating a Bio::Locations object (based on a GenBank style position string) will spawn an array of Bio::Location objects.

## Usage

      locations = Bio::Locations.new('join(complement(500..550), 600..625)')
      locations.each do |loc|
        puts "class = " + loc.class.to_s
        puts "range = #{loc.from}..#{loc.to} (strand = #{loc.strand})"
      end
      # Output would be:
      #   class = Bio::Location
      #   range = 500..550 (strand = -1)
      #   class = Bio::Location
      #   range = 600..625 (strand = 1)

     # For the following three location strings, print the span and range
     ['one-of(898,900)..983',
      'one-of(5971..6308,5971..6309)',
      '8050..one-of(10731,10758,10905,11242)'].each do |loc|
         location = Bio::Locations.new(loc)
         puts location.span
         puts location.range
     end

### GenBank location descriptor classification

#### Definition of the position notation of the GenBank location format

According to the GenBank manual ‘gbrel.txt’, position notations were classified into 10 patterns - (A) to (J).

      3.4.12.2 Feature Location

        The second column of the feature descriptor line designates the
      location of the feature in the sequence. The location descriptor
      begins at position 22. Several conventions are used to indicate
      sequence location.

        Base numbers in location descriptors refer to numbering in the entry,
      which is not necessarily the same as the numbering scheme used in the
      published report. The first base in the presented sequence is numbered
      base 1. Sequences are presented in the 5 to 3 direction.

      Location descriptors can be one of the following:

      (A) 1. A single base;

      (B) 2. A contiguous span of bases;

      (C) 3. A site between two bases;

      (D) 4. A single base chosen from a range of bases;

      (E) 5. A single base chosen from among two or more specified bases;

      (F) 6. A joining of sequence spans;

      (G) 7. A reference to an entry other than the one to which the feature
           belongs (i.e., a remote entry), followed by a location descriptor
           referring to the remote sequence;

      (H) 8. A literal sequence (a string of bases enclosed in quotation marks).

#### Description commented with pattern IDs.

      (C)   A site between two residues, such as an endonuclease cleavage site, is
          indicated by listing the two bases separated by a carat (e.g., 23^24).

      (D)   A single residue chosen from a range of residues is indicated by the
          number of the first and last bases in the range separated by a single
          period (e.g., 23.79). The symbols < and > indicate that the end point
      (I) of the range is beyond the specified base number.

      (B)   A contiguous span of bases is indicated by the number of the first and
          last bases in the range separated by two periods (e.g., 23..79). The
      (I) symbols < and > indicate that the end point of the range is beyond the
          specified base number. Starting and ending positions can be indicated
          by base number or by one of the operators described below.

            Operators are prefixes that specify what must be done to the indicated
          sequence to locate the feature. The following are the operators
          available, along with their most common format and a description.

      (J) complement (location): The feature is complementary to the location
          indicated. Complementary strands are read 5 to 3.

      (F) join (location, location, .. location): The indicated elements should
          be placed end to end to form one contiguous sequence.

      (F) order (location, location, .. location): The elements are found in the
          specified order in the 5 to 3 direction, but nothing is implied about
          the rationality of joining them.

      (F) group (location, location, .. location): The elements are related and
          should be grouped together, but no order is implied.

      (E) one-of (location, location, .. location): The element can be any one,
        but only one, of the items listed.

### Reduction strategy of the position notations

- (A) Location n
- (B) Location n..m
- (C) Location n^m
- (D) (n.m) => Location n
- (E)
  - one-of(n,m,..) => Location n
  - one-of(n..m,..) => Location n..m
- (F)
  - order(loc,loc,..) => join(loc, loc,..)
  - group(loc,loc,..) => join(loc, loc,..)
  - join(loc,loc,..) => Sequence
- (G) ID:loc => Location with ID
- (H) "atgc" => Location only with Sequence
- (I)
  - <n => Location n with lt flag
  - >n => Location n with gt flag
  - <n..m => Location n..m with lt flag
  - n..>m => Location n..m with gt flag
  - <n..>m => Location n..m with lt, gt flag
- (J) complement(loc) => Sequence
- (K) replace(loc, str) => Location with replacement Sequence

### Methods

[] absolute each equals? first last length new range relative size span to_s

### Included Modules

Enumerable

### Attributes

locations | [RW] | (Array) An Array of Bio::Location objects
operator | [RW] | (Symbol or nil) Operator. nil (means :join), :order, or :group (obsolete).

### Public Class methods

new(position)

Parses a GenBank style position string and returns a Bio::Locations object, which contains a list of Bio::Location objects.

      locations = Bio::Locations.new('join(complement(500..550), 600..625)')

Arguments:

- (required) str: GenBank style position string

Returns: | Bio::Locations object

[Source]

         # File lib/bio/location.rb, line 324
    324:   def initialize(position)
    325:     @operator = nil
    326:     if position.is_a? Array
    327:       @locations = position
    328:     else
    329:       position   = gbl_cleanup(position)        # preprocessing
    330:       @locations = gbl_pos2loc(position)        # create an Array of Bio::Location objects
    331:     end
    332:   end

### Public Instance methods

[](n)

Returns nth Bio::Location object.

[Source]

         # File lib/bio/location.rb, line 361
    361:   def [](n)
    362:     @locations[n]
    363:   end

absolute(n, type = nil)

Converts relative position in the locus to position in the whole of the DNA sequence.

This method can for example be used to relate positions in a DNA-sequence with those in RNA. In this use, the optional ’:aa’-flag returns the position of the associated amino-acid rather than the nucleotide.

      loc = Bio::Locations.new('complement(12838..13533)')
      puts loc.absolute(10)          # => 13524
      puts loc.absolute(10, :aa)     # => 13506

Arguments:

- (required) position: nucleotide position within locus
- _:aa_: flag to be used if position is a aminoacid position rather than a nucleotide position

Returns: | position within the whole of the sequence

[Source]

         # File lib/bio/location.rb, line 451
    451:   def absolute(n, type = nil)
    452:     case type
    453:     when :location
    454:       ;
    455:     when :aa
    456:       n = (n - 1) * 3 + 1
    457:       rel2abs(n)
    458:     else
    459:       rel2abs(n)
    460:     end
    461:   end

each() {|x| ...}

Iterates on each Bio::Location object.

[Source]

         # File lib/bio/location.rb, line 354
    354:   def each
    355:     @locations.each do |x|
    356:       yield(x)
    357:     end
    358:   end

equals?(other)

Evaluate equality of Bio::Locations object.

[Source]

         # File lib/bio/location.rb, line 342
    342:   def equals?(other)
    343:     if ! other.kind_of?(Bio::Locations)
    344:       return nil
    345:     end
    346:     if self.sort == other.sort
    347:       return true
    348:     else
    349:       return false
    350:     end
    351:   end

first()

Returns first Bio::Location object.

[Source]

         # File lib/bio/location.rb, line 366
    366:   def first
    367:     @locations.first
    368:   end

last()

Returns last Bio::Location object.

[Source]

         # File lib/bio/location.rb, line 371
    371:   def last
    372:     @locations.last
    373:   end

length()

Returns a length of the spliced RNA.

[Source]

         # File lib/bio/location.rb, line 390
    390:   def length
    391:     len = 0
    392:     @locations.each do |x|
    393:       if x.sequence
    394:         len += x.sequence.size
    395:       else
    396:         len += (x.to - x.from + 1)
    397:       end
    398:     end
    399:     len
    400:   end

range()

Similar to span, but returns a Range object min..max

[Source]

         # File lib/bio/location.rb, line 384
    384:   def range
    385:     min, max = span
    386:     min..max
    387:   end

relative(n, type = nil)

Converts absolute position in the whole of the DNA sequence to relative position in the locus.

This method can for example be used to relate positions in a DNA-sequence with those in RNA. In this use, the optional ’:aa’-flag returns the position of the associated amino-acid rather than the nucleotide.

      loc = Bio::Locations.new('complement(12838..13533)')
      puts loc.relative(13524)        # => 10
      puts loc.relative(13506, :aa)   # => 3

Arguments:

- (required) position: nucleotide position within whole of the sequence
- _:aa_: flag that lets method return position in aminoacid coordinates

Returns: | position within the location

[Source]

         # File lib/bio/location.rb, line 419
    419:   def relative(n, type = nil)
    420:     case type
    421:     when :location
    422:       ;
    423:     when :aa
    424:       if n = abs2rel(n)
    425:         (n - 1) / 3 + 1
    426:       else
    427:         nil
    428:       end
    429:     else
    430:       abs2rel(n)
    431:     end
    432:   end

size()

Alias for length

span()

Returns an Array containing overall min and max position [min, max] of this Bio::Locations object.

[Source]

         # File lib/bio/location.rb, line 377
    377:   def span
    378:     span_min = @locations.min { |a,b| a.from <=> b.from }
    379:     span_max = @locations.max { |a,b| a.to   <=> b.to   }
    380:     return span_min.from, span_max.to
    381:   end

to_s()

String representation.

Note: In some cases, it fails to detect whether "complement(join(…))" or "join(complement(..))", and whether "complement(order(…))" or "order(complement(..))".

Returns: | String

[Source]

         # File lib/bio/location.rb, line 472
    472:   def to_s
    473:     return '' if @locations.empty?
    474:     complement_join = false
    475:     locs = @locations
    476:     if locs.size >= 2 and locs.inject(true) do |flag, loc|
    477:         # check if each location is complement
    478:         (flag && (loc.strand == -1) && !loc.xref_id)
    479:       end and locs.inject(locs[0].from) do |pos, loc|
    480:         if pos then
    481:           (pos >= loc.from) ? loc.from : false
    482:         else
    483:           false
    484:         end
    485:       end then
    486:       locs = locs.reverse
    487:       complement_join = true
    488:     end
    489:     locs = locs.collect do |loc|
    490:       lt = loc.lt ? '<' : ''
    491:       gt = loc.gt ? '>' : ''
    492:       str = if loc.from == loc.to then
    493:               "#{lt}#{gt}#{loc.from.to_i}"
    494:             elsif loc.carat then
    495:               "#{lt}#{loc.from.to_i}^#{gt}#{loc.to.to_i}"
    496:             else
    497:               "#{lt}#{loc.from.to_i}..#{gt}#{loc.to.to_i}"
    498:             end
    499:       if loc.xref_id and !loc.xref_id.empty? then
    500:         str = "#{loc.xref_id}:#{str}"
    501:       end
    502:       if loc.strand == -1 and !complement_join then
    503:         str = "complement(#{str})"
    504:       end
    505:       if loc.sequence then
    506:         str = "replace(#{str},\"#{loc.sequence}\")"
    507:       end
    508:       str
    509:     end
    510:     if locs.size >= 2 then
    511:       op = (self.operator || 'join').to_s
    512:       result = "#{op}(#{locs.join(',')})"
    513:     else
    514:       result = locs[0]
    515:     end
    516:     if complement_join then
    517:       result = "complement(#{result})"
    518:     end
    519:     result
    520:   end

[Validate]