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

## Description

The Bio::Location class describes the position of a genomic locus. Typically, Bio::Location objects are created automatically when the user creates a Bio::Locations object, instead of initialized directly.

## Usage

      location = Bio::Location.new('500..550')
      puts "start=" + location.from.to_s + ";end=" + location.to.to_s

      #, or better: through Bio::Locations
      locations = Bio::Locations.new('500..550')
      locations.each do |location|
        puts "start=" + location.from.to_s + ";end=" + location.to.to_s
      end

### Methods

<=> == complement new range replace

### Included Modules

Comparable

### Attributes

carat | [RW] | (true, false or nil) true if the location indicates the site between two adjoining nucleotides
from | [RW] | (Integer) start position of the location
gt | [RW] | (true, false or nil) true if the position contains ’>’
lt | [RW] | (true, false or nil) true if the position contains ’<’
sequence | [RW] | (String) literal sequence of the location
strand | [RW] | (Integer) strand direction of the location (forward => 1 or complement => -1)
to | [RW] | (Integer) end position of the location
xref_id | [RW] | (String) link to the external entry as GenBank ID

### Public Class methods

new(location = nil)

Parses a‘location’ segment, which can be ‘ID:’ + (‘n’ or ‘n..m’ or ‘n^m’ or "seq") with ’<’ or ’>’, and returns a Bio::Location object.

      location = Bio::Location.new('500..550')

Arguments:

- (required) str: GenBank style position string (see Bio::Locations documentation)

Returns: | the Bio::Location object

[Source]

        # File lib/bio/location.rb, line 45
    45:   def initialize(location = nil)
    46:
    47:     if location
    48:       if location =~ /:/                                # (G) ID:location
    49:         xref_id, location = location.split(':')
    50:       end
    51:       if location =~ /</                                # (I) <,>
    52:         lt = true
    53:       end
    54:       if location =~ />/
    55:         gt = true
    56:       end
    57:     end
    58:
    59:     # s : start base, e : end base => from, to
    60:     case location
    61:     when /^[<>]?(\d+)$/                                 # (A, I) n
    62:       s = e = $1.to_i
    63:     when /^[<>]?(\d+)\.\.[<>]?(\d+)$/                   # (B, I) n..m
    64:       s = $1.to_i
    65:       e = $2.to_i
    66:       if e - s < 0
    67: #       raise "Error: invalid range : #{location}"
    68:         $stderr.puts "[Warning] invalid range : #{location}" if $DEBUG
    69:       end
    70:     when /^[<>]?(\d+)\^[<>]?(\d+)$/                     # (C, I) n^m
    71:       s = $1.to_i
    72:       e = $2.to_i
    73:       carat = true
    74:       if e - s != 1 or e != 1 # assert n^n+1 or n^1
    75: #       raise "Error: invalid range : #{location}"
    76:         $stderr.puts "[Warning] invalid range : #{location}" if $DEBUG
    77:       end
    78:     when /^"?([ATGCatgc]+)"?$/                  # (H) literal sequence
    79:       sequence = $1.downcase
    80:       s = e = nil
    81:     when nil
    82:       ;
    83:     else
    84:       raise "Error: unknown location format : #{location}"
    85:     end
    86:
    87:     @from       = s             # start position of the location
    88:     @to         = e             # end position of the location
    89:     @strand     = 1             # strand direction of the location
    90:                                 #   forward => 1 or complement => -1
    91:     @sequence   = sequence      # literal sequence of the location
    92:     @lt         = lt            # true if the position contains '<'
    93:     @gt         = gt            # true if the position contains '>'
    94:     @xref_id    = xref_id       # link to the external entry as GenBank ID
    95:     @carat      = carat         # true if the location indicates the site
    96:                                 # between two adjoining nucleotides
    97:   end

### Public Instance methods

<=>(other)

Check where a Bio::Location object is located compared to another Bio::Location object (mainly to facilitate the use of Comparable). A location A is upstream of location B if the start position of location A is smaller than the start position of location B. If they‘re the same, the end positions are checked.

Arguments:

- (required) _other location_: a Bio::Location object

Returns::

- 1 if self < other location
- -1 if self > other location
- 0 if both location are the same
- nil if the argument is not a Bio::Location object

[Source]

         # File lib/bio/location.rb, line 163
    163:   def <=>(other)
    164:     if ! other.kind_of?(Bio::Location)
    165:       return nil
    166:     end
    167:
    168:     if @from.to_f < other.from.to_f
    169:       return -1
    170:     elsif @from.to_f > other.from.to_f
    171:       return 1
    172:     end
    173:
    174:     if @to.to_f < other.to.to_f
    175:       return -1
    176:     elsif @to.to_f > other.to.to_f
    177:       return 1
    178:     end
    179:     return 0
    180:   end

==(other)

If other is equal with the self, returns true. Otherwise, returns false.

Arguments:

- (required) other: any object

Returns: | true or false

[Source]

         # File lib/bio/location.rb, line 188
    188:   def ==(other)
    189:     return true if super(other)
    190:     return false unless other.instance_of?(self.class)
    191:     flag = false
    192:     [ :from, :to, :strand, :sequence, :lt, :gt,
    193:       :xref_id, :carat ].each do |m|
    194:       begin
    195:         flag = (self.__send__(m) == other.__send__(m))
    196:       rescue NoMethodError, ArgumentError, NameError
    197:         flag = false
    198:       end
    199:       break unless flag
    200:     end
    201:     flag
    202:   end

complement()

Complements the sequence location (i.e. alternates the strand). Note that it is destructive method (i.e. modifies itself), but it does not modify the "sequence" attribute.

Returns: | the Bio::Location object

[Source]

         # File lib/bio/location.rb, line 129
    129:   def complement
    130:     @strand *= -1
    131:     self                                        # return Location object
    132:   end

range()

Returns the range (from..to) of the location as a Range object.

[Source]

         # File lib/bio/location.rb, line 146
    146:   def range
    147:     @from..@to
    148:   end

replace(sequence)

Replaces the sequence of the location.

Arguments:

- (required) sequence: sequence to be used to replace the sequence at the location

Returns: | the Bio::Location object

[Source]

         # File lib/bio/location.rb, line 140
    140:   def replace(sequence)
    141:     @sequence = sequence.downcase
    142:     self                                        # return Location object
    143:   end

[Validate]