Summary

Bio::DB::SeqFeature::Segment -- Location-based access to genome annotation data

Package variables

Included modules

Inherit

, Bio::RangeI Bio::SeqFeature::CollectionI

Synopsis

 use Bio::DB::SeqFeature::Store;
 # Open the sequence database
 my $db      = Bio::DB::SeqFeature::Store->new( -adaptor => 'DBI::mysql',
                                                -dsn     => 'dbi:mysql:test');
 my $segment  = $db->segment('Chr1',5000=>6000);
 my @features = $segment->features('mRNA','match');

Description

The segment object simplifies access to Bio::DB::SeqFeature store by
acting as a placeholder for a region of the genome. You can replace
this statement:

 @features = $db->features(-seq_id=>'Chr1',
                           -start=>5000,
                           -end=>6000,
                           -types=>['mRNA','match','repeat_region']);

with these statements:

 $segment = $db->segment('Chr1',5000=>6000);
 @features = $segment->features('mRNA','match','repeat_region');

You can also initialize a segment from an existing SeqFeature
object. The range will be picked up from the SeqFeature boundaries:

 $segment = Bio::DB::SeqFeature::Segment->new($feature);        # for Bio::DB::SeqFeature
 $segment = Bio::DB::SeqFeature::Segment->new($feature,$store); # for other Bio::SeqFeatureI objects

The segment object implements the full Bio::SeqFeature::CollectionI
interface, thereby allowing you to iterate over all features in the
range.

Methods

Methods description

 Title   : new
 Usage   : $segment = Bio::DB::SeqFeature::Segment->new(@options)
 Function: create a new Segment object
 Returns : A Bio::DB::SeqFeature::Segment object
 Args    : several - see below
 Status  : public

 $segment = Bio::DB::SeqFeature::Segment->new($store,$seqid,$start,$end,$strand)

 $segment = Bio::DB::SeqFeature::Segment->new($seqfeature [,$store]);

 Title   : features
 Usage   : @features = $segment->features(@args)
 Function: fetch seqfeatures that overlap the segment
 Returns : list of features
 Args    : see below
 Status  : Public

  Argument       Value
  --------       -----

 Location filters:
  -strand        Strand
  -range_type    Type of range match ('overlaps','contains','contained_in')

 Name filters:
  -name          Name of feature (may be a glob expression)
  -aliases       If true, match aliases as well as display names
  -class         Archaic argument for backward compatibility.
                  (-class=>'Clone',-name=>'ABC123') is equivalent
                  to (-name=>'Clone:ABC123')

 Type filters:
  -types         List of feature types (array reference) or one type (scalar)
  -type          Synonym for the above
  -primary_tag   Synonym for the above

  -attributes    Hashref of attribute=>value pairs as per
                    get_features_by_attribute(). Multiple alternative values
                    can be matched by providing an array reference.
  -attribute     synonym for -attributes

 @features = $segment->features;

 @features = $segment->features('mRNA');

 @features = $segment->features(-range_type=>'contains');

 @features = $segment->features(-attributes=>{confirmed=>1},-type=>'mRNA');

 Title   : get_seq_stream
 Usage   : $iterator = $segment->get_seq_stream(@args)
 Function: return an iterator across all features in the database
 Returns : a Bio::DB::SeqFeature::Store::Iterator object
 Args    : (optional) the feature() method
 Status  : public

  my $iterator = $db->get_seq_stream;
  while (my $feature = $iterator->next_seq) {
    print $feature->primary_tag,' ',$feature->display_name,"\n";
  }

 Title   : store
 Usage   : $store = $segment->store
 Function: return the Bio::DB::SeqFeature::Store object associated with the segment
 Returns : a Bio::DB::SeqFeature::Store: object
 Args    : none
 Status  : public

 Title   : as_string
 Usage   : $name = $segment->as_string
 Function: expands the object into a human-readable string
 Returns : "seq_id:start..end"
 Args    : none
 Status  : public

 Title   : rel2abs
 Usage   : @coords = $s->rel2abs(@coords)
 Function: convert relative coordinates into absolute coordinates
 Returns : a list of absolute coordinates
 Args    : a list of relative coordinates
 Status  : Public

 Title   : abs2rel
 Usage   : @rel_coords = $s->abs2rel(@abs_coords)
 Function: convert absolute coordinates into relative coordinates
 Returns : a list of relative coordinates
 Args    : a list of absolute coordinates
 Status  : Public

Methods code

sub new {

  my $class = shift;
  my ($store,$seqid,$start,$end,$strand);
  if (ref $_[0] && UNIVERSAL::isa($_[0],'Bio::SeqFeatureI')) {
    my $seqfeature = shift;
    $store      = shift;
    $store       ||= eval {$seqfeature->object_store};
    $class->throw("I could not derive the Bio::DB::SeqFeature::Store object from the arguments passed to Bio::DB::SeqFeature::Segment->new(). Please pass the Store object as the second argument") unless $store;
    $seqid = $seqfeature->seq_id;
    $start = $seqfeature->start;
    $end   = $seqfeature->end;
    $strand= $seqfeature->strand;
  }
  else {
    ($store,$seqid,$start,$end,$strand) = @_;
  }
  return bless {
		store => $store,
		seqid => $seqid,
		start => $start,
		end   => $end,
		strand => $strand,
	       },ref($class) || $class;

}

sub features {

  my $self = shift;
  my @args;
  if (@_ == 0) {
    @args = ();
  }
  elsif ($_[0] !~/^-/) {
    my @types = @_;
    @args = (-type=>\@types);
  } else {
    @args = @_;
  }
  $self->{store}->features(@args,-seqid=>$self->{seqid},-start=>$self->{start},-end=>$self->{end});

}

sub types {

    my $self = shift;
    my %types;
    my $iterator = $self->get_seq_stream(@_);
    while (my $f = $iterator->next_seq) {
	$types{$f->type}++;
    }
    return %types;

}

sub get_seq_stream {

  my $self = shift;
  $self->{store}->get_seq_stream(@_,-seqid=>$self->{seqid},-start=>$self->{start},-end=>$self->{end});

}

sub factory {

 shift->{store}

}

sub store {

 shift->{store}

}

sub type {

 shift->primary_tag

}

sub as_string {

  my $self = shift;
  my $label = $self->seq_id;
  my $start = $self->start || '';
  my $end   = $self->end   || '';
  return "$label:$start..$end";

}

sub rel2abs {

  my $self = shift;
  my @result;

  my ($start,$strand) = ($self->start,$self->strand);
  @result = $strand < 0 ? map { $start - $_ + 1 } @_
                        : map { $_ + $start - 1 } @_;
  # if called with a single argument, caller will expect a single scalar reply
  # not the size of the returned array!
  return $result[0] if @result == 1 and !wantarray;
  @result;

}

sub abs2rel {

  my $self = shift;
  my @result;

  my ($start,$strand) = ($self->start,$self->abs_strand);
  @result = $strand < 0 ? map { $start - $_ + 1 } @_
                        : map { $_ - $start + 1 } @_;

  # if called with a single argument, caller will expect a single scalar reply
  # not the size of the returned array!
  return $result[0] if @result == 1 and !wantarray;
  @result;

}

sub start {

 shift->{start}

}

sub end {

 shift->{end}

}

sub seq_id {

 shift->{seqid}

}

sub strand {

 shift->{strand}

}

sub ref {

 shift->seq_id

}

sub length {

  my $self = shift;
  return abs($self->end - $self->start) +1;

}

sub source_tag {

 __PACKAGE__

}

sub display_name {

 shift->as_string

}

sub name {

 shift->display_name

}

sub class {

 'region'

}

sub abs_ref {

 shift->ref

}

sub abs_start {

 shift->start

}

sub abs_end {

 shift->end

}

sub abs_strand {

 shift->strand

}

sub get_SeqFeatures {

}

sub get_all_tags {

}

sub get_tag_values {

}

sub add_tag_value {

}

sub remove_tag {

}

sub has_tag {

}

sub seq {

  my $self = shift;
  require Bio::PrimarySeq unless Bio::PrimarySeq->can('new');
  my ($start,$end) = ($self->start,$self->end);
  if ($self->strand < 0) {
    ($start,$end) = ($end,$start);
  }
  return Bio::PrimarySeq->new(
			      -seq => $self->store->fetch_sequence($self->seq_id,$start,$end),
			      -id  => $self->display_name);

}

sub subseq {

  my $self = shift;
  my ($newstart,$newstop) = @_;
  my $store = $self->store or return;
  my $seq   = $store->fetch_sequence($self->seq_id,$self->start+$newstart-1,$self->end+$newstop-1);
  return Bio::PrimarySeq->new(-seq=>$seq);

}

sub dna {

  my $seq = shift->seq;
  $seq    = $seq->seq if CORE::ref($seq);
  return $seq;

}

sub entire_seq {

  my $self = shift;
  require Bio::PrimarySeq unless Bio::PrimarySeq->can('new');
  return Bio::PrimarySeq->new(
			      -seq => $self->store->fetch_sequence($self->seq_id),
			      -id  => $self->seq_id);

}

sub location {

  my $self = shift;
  require Bio::Location::Simple unless Bio::Location::Simple->can('new');  
  my $loc = Bio::Location::Simple->new(-start  => $self->start,
				    -end    => $self->end,
				       -strand => $self->strand);
  $loc->strand($self->strand);
  warn("strand will be ", $self->strand, "\n") if $self->strand < 0;
  return $loc;

}

sub primary_id {

  my $self = shift;
  my $d    = $self->{primary_id};
  $self->{primary_id} = shift if @_;
  $d;

}

sub score {

 return

}

sub stop {

 shift->end

}

sub absolute {

 return 1

}

sub desc {

 shift->as_string

}

sub display_id {

 shift->display_name

}

sub primary_seq {

 shift->seq

}

sub accession_number {

 return undef }  # intended return undef

}

General documentation

The following are public methods intended for external use.

 Title   : primary_tag,type
 Usage   : $primary_tag = $segment->primary_tag
 Function: returns the string "region"
 Returns : "region"
 Args    : none
 Status  : public

The primary_tag method returns the constant tag "region". type() is a
synonym for this method.

For convenience, segments are interchangeable with Bio::SeqFeature
objects in many cases. This means that segments can be passed to
BioPerl modules that expect Bio::SeqFeature objects and they should
work as expected. The primary tag of segment objects is "region"
(SO:0000001 "Continous sequence >=1 base pair").
All these methods are read-only except for the primary_id, which can
be get or set.
The following Bio::SeqFeatureI methods are supported:

This is an early version, so there are certainly some bugs. Please
use the BioPerl bug tracking system to report bugs.

bioperl,
Bio::DB::SeqFeature::Store,
Bio::DB::SeqFeature::GFF3Loader,
Bio::DB::SeqFeature::Store::DBI::mysql,
Bio::DB::SeqFeature::Store::bdb

Lincoln Stein <lstein@cshl.org>.
Copyright (c) 2006 Cold Spring Harbor Laboratory.
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.