view release on metacpan or  search on metacpan

lib/Bio/EnsEMBL/Utils/AssemblyProjector.pm  view on Meta::CPAN

In addition to the "raw" projecting of features and slices, the methods
in this module also apply some sensible rules to the results of the
projection (like discarding unwanted results or merging fragmented
projections). These are the rules (depending on configuration):

Discard the projected feature/slice if:

  1. it doesn't project at all (no segments returned)
  2. [unless MERGE_FRAGMENTS is set] the projection is fragmented (more
     than one segment)
  3. [if CHECK_LENGTH is set] the projection doesn't have the same
     length as the original feature/slice
  4. all segments are on same chromosome and strand

If a projection fails any of these rules, undef is returned instead of
a projected feature/slice. You can use the last_status() method to find
out about the results of the rules tests.

Also note that when projecting features, only a shallow projection is
performed, i.e. other features attached to your features (e.g. the
transcripts of a gene) are not projected automatically, so it will be
the responsability of the user code project all levels of features
involved.

=head1 METHODS

  new
  project
  old_to_new
  new_to_old
  adaptor
  external_source
  old_assembly
  new_assembly
  merge_fragments
  check_length

=head1 RELATED MODULES

The process of creating a whole genome alignment between two assemblies
(which is the basis for the use of the methods in this class) is done by
a series of scripts. Please see

  ensembl/misc-scripts/assembly/README

for a high-level description of this process, and POD in the individual
scripts for the details.

=cut

package Bio::EnsEMBL::Utils::AssemblyProjector;
$Bio::EnsEMBL::Utils::AssemblyProjector::VERSION = '114.0.0';
use strict;
use warnings;
no warnings qw(uninitialized);

use Bio::EnsEMBL::Utils::Exception qw(throw warning);
use Bio::EnsEMBL::Utils::Argument qw(rearrange);
use Bio::EnsEMBL::Slice;
use Scalar::Util qw(weaken);

=head2 new

  Arg [ADAPTOR]         : Bio::EnsEMBL::DBSQL::DBAdaptor $adaptor - a db adaptor
                          for a database containing the assembly mapping
  Arg [EXTERNAL_SOURCE] : (optional) Boolean $external_source - indicates if
                          source is from a different database
  Arg [OLD_ASSEMBLY]    : name of the old assembly
  Arg [OLD_ASSEMBLY]    : name of the new assembly
  Arg [OBJECT_TYPE]     : (optional) object type ('slice' or 'feature')
  Arg [MERGE_FRAGMENTS] : (optional) Boolean - determines if segments are merged
                          to return a single object spanning all segments
                          (default: true)
  Arg [CHECK_LENGTH]    : (optional) Boolean - determines if projected objects
                          have to have same length as original (default: false)
  Example     : my $ap = Bio::EnsEMBL::Utils::AssemblyProjector->new(
                  -DBADAPTOR    => $dba,
                  -OLD_ASSEMBLY => NCBIM36,
                  -NEW_ASSEMBLY => NCBIM37,
                );
  Description : Constructor.
  Return type : a Bio::EnsEMBL::Utils::AssemblyProjector object
  Exceptions  : thrown on missing arguments
                thrown on invalid OBJECT_TYPE
  Caller      : general
  Status      : At Risk
              : under development

=cut

sub new {
  my $caller = shift;
  my $class = ref($caller) || $caller;

  my ($adaptor, $external_source, $old_assembly, $new_assembly,
      $merge_fragments, $check_length) = rearrange([qw(ADAPTOR EXTERNAL_SOURCE 
        OLD_ASSEMBLY NEW_ASSEMBLY MERGE_FRAGMENTS CHECK_LENGTH)], @_);

  unless ($adaptor and ref($adaptor) and
          $adaptor->isa('Bio::EnsEMBL::DBSQL::DBAdaptor')) {
    throw("You must provide a DBAdaptor to a database containing the assembly mapping.");
  }

  unless ($old_assembly and $new_assembly) {
    throw("You must provide an old and new assembly name.");
  }

  my $self = {};
  bless ($self, $class);

  # initialise
  $self->adaptor($adaptor);
  $self->{'old_assembly'} = $old_assembly;
  $self->{'new_assembly'} = $new_assembly;
  
  # by default, merge fragments
  $self->{'merge_fragments'} = $merge_fragments || 1;

  # by default, do not check length
  $self->{'check_length'} = $check_length || 0;

lib/Bio/EnsEMBL/Utils/AssemblyProjector.pm  view on Meta::CPAN

    $object->strand($new_slice->strand);
    $object->slice($new_slice->seq_region_Slice);

    # undef dbID and adaptor so you can store the feature in the target db
    $object->dbID(undef);
    $object->adaptor(undef);

    return $object;
  }
  
}


=head2 old_to_new

  Arg[1]      : Bio::EnsEMBL::Slice or Bio::EnsEMBL::Feature $object -
                the object to project
  Example     : my $new_slice = $assembly_projector->old_to_new($old_slice);
  Description : Projects a Slice or Feature from old to new assembly.
                This method is just a convenience wrapper for $self->project.
  Return type : same a Arg 1, or undef
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development

=cut

sub old_to_new {
  my ($self, $object) = @_;
  return $self->project($object, $self->new_assembly);
}


=head2 new_to_old

  Arg[1]      : Bio::EnsEMBL::Slice or Bio::EnsEMBL::Feature $object -
                the object to project
  Example     : my $old_slice = $assembly_projector->new_to_old($new_slice, 1);
  Description : Projects a Slice or Feature from new to old assembly.
                This method is just a convenience wrapper for $self->project.
  Return type : same a Arg 1, or undef
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development

=cut

sub new_to_old {
  my ($self, $object) = @_;
  return $self->project($object, $self->old_assembly);
}


#
# accessors
#
sub adaptor {
  my $self = shift;
  weaken($self->{'adaptor'} = shift) if (@_);
  return $self->{'adaptor'};
}


sub external_source {
  my $self = shift;
  $self->{'external_source'} = shift if (@_);
  return $self->{'external_source'};
}


sub old_assembly {
  my $self = shift;
  $self->{'old_assembly'} = shift if (@_);
  return $self->{'old_assembly'};
}


sub new_assembly {
  my $self = shift;
  $self->{'new_assembly'} = shift if (@_);
  return $self->{'new_assembly'};
}


sub merge_fragments {
  my $self = shift;
  $self->{'merge_fragments'} = shift if (@_);
  return $self->{'merge_fragments'};
}


sub check_length {
  my $self = shift;
  $self->{'check_length'} = shift if (@_);
  return $self->{'check_length'};
}


sub last_status {
  my $self = shift;
  $self->{'last_status'} = shift if (@_);
  return $self->{'last_status'};
}


1;