package Bio::EnsEMBL::IntronSupportingEvidence;

=pod

=head1 LICENSE

  Copyright (c) 1999-2013 The European Bioinformatics Institute and
  Genome Research Limited.  All rights reserved.

  This software is distributed under a modified Apache license.
  For license details, please see

    http://www.ensembl.org/info/about/code_licence.html

=head1 CONTACT

  Please email comments or questions to the public Ensembl
  developers list at <dev@ensembl.org>.

  Questions may also be sent to the Ensembl help desk at
  <helpdesk@ensembl.org>.

=head1 NAME

Bio::EnsEMBL::IntronSupportingEvidence

=head1 DESCRIPTION

Formalises an Intron with information about why it is a believed Intron. This 
serves as a parallel object to Bio::EnsEMBL::Intron which you can use 
to populate values in this field from. They are different objects though
due to Intron's non-existence as a DB data structure.

=head1 SYNOPSIS

  #Example setups a ISE from the first two Exons
  my ($five_prime_exon, $three_prime_exon) = @{$transcript->get_all_Exons()}[0..1];
  my $intron = Bio::EnsEMBL::Intron->new($five_prime_exon, $three_prime_exon);

=head1 METHODS

=cut


use strict;
use warnings;
use base qw/Bio::EnsEMBL::Feature/;

use Bio::EnsEMBL::Intron;
use Bio::EnsEMBL::Utils::Argument qw/rearrange/;
use Bio::EnsEMBL::Utils::Exception qw/throw/;
use Bio::EnsEMBL::Utils::Scalar qw/assert_ref/;

our %SUPPORTED_TYPES = map { $_ => 1 } qw/NONE DEPTH/;

=head2 new

  Arg [-ANALYSIS]     : Bio::EnsEMBL::Analysis The analysis this intron is linked to
  Arg [-START]        : int - start postion of the IntronSupportingEvidence
  Arg [-END]          : int - end position of the IntronSupportingEvidence
  Arg [-STRAND]       : int - strand the IntronSupportingEvidence is on
  Arg [-SLICE]        : Bio::EnsEMBL::Slice - the slice the IntronSupportingEvidence is on
  Arg [-INTRON]       : Bio::EnsEMBL::Intron Intron the evidence is based 
                        on. Useful if you are not specifying the location 
                        parameters as we will take them from this 
  Arg [-HIT_NAME]     : String The name of the hit
  Arg [-SCORE]        : Double The score associated with the supporting evidence
  Arg [-SCORE_TYPE]   : String The type of score we are representing
  Example             : Bio::EnsEMBL::IntronSupportingEvidence->new(
                          -ANALYSIS => $analysis, -INTRON => $intron, 
                          -SCORE => 100, -SCORE_TYPE => 'DEPTH');
  Description         : Returns a new instance of this object
  Returntype          : Bio::EnsEMBL::IntronSupportEvidence
  Exceptions          : Thrown if data is not as requested

=cut

sub new {
  my ($class, @args) = @_;
  
  my $self = $class->SUPER::new(@args);
  
  my ($intron, $hit_name, $score, $score_type, $is_splice_canonical) = 
    rearrange([qw/intron hit_name score score_type is_splice_canonical/], @args);
  
  if($intron) {
    $self->set_values_from_Intron($intron);
  }
  $self->hit_name($hit_name) if $hit_name;
  $self->score($score) if $score;
  $self->score_type($score_type) if $score_type;
  $self->is_splice_canonical($is_splice_canonical) if $is_splice_canonical;
  
  return $self;
}

=head2 set_values_from_Intron

  Arg [1]     : Bio::EnsEMBL::Intron The intron to base this object on
  Example     : $ise->set_values_from_Intron($intron);
  Description : Sets the start, end, strand and slice of this ISE instance
                using values from the given Intron object.
  Returntype  : None
  Exceptions  : Thrown if data is not as requested

=cut

sub set_values_from_Intron {
  my ($self, $intron) = @_;
  assert_ref($intron, 'Bio::EnsEMBL::Intron', 'intron');
  $self->start($intron->start());
  $self->end($intron->end());
  $self->strand($intron->strand());
  $self->slice($intron->slice());
  $self->is_splice_canonical($intron->is_splice_canonical());
  return;
}

=head2 is_splice_canonical

  Arg [1]     : Boolean
  Example     : $ise->is_splice_canonical(1);
  Description : Getter/setter for is_splice_canonical. Splice canonical 
                indicates those Introns which have a splice junction which 
                is structured as expected 
  Returntype  : Boolean
  Exceptions  : 

=cut

sub is_splice_canonical {
  my ($self, $is_splice_canonical) = @_;
  $self->{'is_splice_canonical'} = $is_splice_canonical if defined $is_splice_canonical;
  return $self->{'is_splice_canonical'};
}

=head2 get_Intron

  Arg [1]     : Bio::EnsEMBL::Transcript
  Example     : my $intron = $ise->intron($transcript);
  Description : Provides access to an Intron object by using a given transcript 
                object and its associcated array of Exons.
  Returntype  : Bio::EnsEMBL::Intron
  Exceptions  : None

=cut

sub get_Intron {
  my ($self, $transcript) = @_;
  assert_ref($transcript, 'Bio::EnsEMBL::Transcript', 'transcript');
  my $five_prime = $self->find_previous_Exon($transcript);
  my $three_prime = $self->find_next_Exon($transcript);
  return Bio::EnsEMBL::Intron->new($five_prime, $three_prime);
}

=head2 hit_name

  Arg [1]     : String name of the hit
  Example     : $ise->hit_name('hit');
  Description : Getter/setter for hit name i.e. an identifier for the alignments
  Returntype  : String
  Exceptions  : None

=cut

sub hit_name {
  my ($self, $hit_name) = @_;
  $self->{'hit_name'} = $hit_name if defined $hit_name;
  return $self->{'hit_name'};
}

=head2 score

  Arg [1]     : Number; the score associated with this feature
  Example     : $ise->score(100);
  Description : Getter/setter for score
  Returntype  : Number
  Exceptions  : None

=cut

sub score {
  my ($self, $score) = @_;
  $self->{'score'} = $score if defined $score;
  return $self->{'score'};
}

=head2 score_type

  Arg [1]     : String the enum type. Currently only allowed NONE or DEPTH
  Example     : $ise->score_type('DEPTH');
  Description : Gets and sets the type of score this instance represents
  Returntype  : String
  Exceptions  : Thrown if given an unsupported type of data

=cut

sub score_type {
  my ($self, $score_type) = @_;
  if(defined $score_type) {
    if(! $SUPPORTED_TYPES{$score_type}) {
      my $values = join(q{, }, keys %SUPPORTED_TYPES);
      throw "The score_type '$score_type' is not allowed. Allowed values are [${values}]";
    }
  }
  $self->{'score_type'} = $score_type if defined $score_type;
  return $self->{'score_type'};
}

=head2 has_linked_transcripts

  Example     : $ise->has_linked_transcripts();
  Description : Returns true if we have transcripts linked to this ISE
  Returntype  : Boolean
  Exceptions  : Thrown if we do not have an attached adaptor

=cut

sub has_linked_transcripts {
  my ($self) = @_;
  throw "No attached adaptor. Cannot find linked Transcripts unless this is a persisted object" unless $self->adaptor();
  my $transcript_ids = $self->adaptor()->list_linked_transcript_ids($self);
  return scalar(@{$transcript_ids}) ? 1 : 0;
}

=head2 equals

  Arg [1]     : Bio::EnsEMBL::IntronSupportEvidence Object to compare to
  Example     : $ise->equals($another_ise);
  Description : Asserts if the given IntronSupportEvidence instance was equal to this
  Returntype  : Boolean
  Exceptions  : None

=cut

sub equals {
  my ($self, $other) = @_;
  my $equal = $self->SUPER::equals($other);
  return 0 if ! $equal;
  return ( 
    ($self->hit_name()||q{}) eq ($other->hit_name()||q{}) &&
    ($self->score_type() eq $other->score_type()) &&
    ($self->score() == $other->score())) ? 1 : 0;
}

=head2 find_previous_Exon

  Arg [1]     : Bio::EnsEMBL::Transcript Transcript to search for the Exons from
  Example     : $ise->find_previous_Exon($transcript);
  Description : Loops through those Exons available from the Transcript and
                attempts to find one which was the 5' flanking exon. If the
                object has already been persisted we will use dbIDs to
                find the Exons
  Returntype  : Bio::EnsEMBL::Exon
  Exceptions  : None

=cut

sub find_previous_Exon {
  my ($self, $transcript) = @_;
  
  #Use DB IDs if we have them
  my $exon_id;
  if($self->adaptor()) {
    my @ids = $self->adaptor()->fetch_flanking_exon_ids($self, $transcript);
    $exon_id = $ids[0] if @ids; 
  }
  
  my $exons = $transcript->get_all_Exons();
  
  my $start = $self->start();
  my $end = $self->end();
  foreach my $exon (@{$exons}) {
    if($exon_id) {
      return $exon if $exon->dbID() == $exon_id;
      next;
    }
    if($self->strand() == 1) {
      return $exon if $exon->end() == $start-1;
    }
    else {
      return $exon if $exon->start() == $end+1;
    }
  }
  return;
}

=head2 find_next_Exon

  Arg [1]     : Bio::EnsEMBL::Transcript Transcript to search for the Exons from
  Example     : $ise->find_next_Exon($transcript);
  Description : Loops through those Exons available from the Transcript and
                attempts to find one which was the 3' flanking exon. If the
                object has already been persisted we will use dbIDs to
                find the Exons
  Returntype  : Bio::EnsEMBL::Exon
  Exceptions  : None

=cut

sub find_next_Exon {
  my ($self, $transcript) = @_;
  
  #Use DB IDs if we have them
  my $exon_id;
  if($self->adaptor()) {
    my @ids = $self->adaptor()->fetch_flanking_exon_ids($self, $transcript);
    $exon_id = $ids[1] if @ids; 
  }
  
  my $exons = $transcript->get_all_Exons();
  my $start = $self->start();
  my $end = $self->end();
  foreach my $exon (@{$exons}) {
    if($exon_id) {
      return $exon if $exon->dbID() == $exon_id;
      next;
    }
    if($self->strand() == 1) {
      return $exon if $exon->start() == $end+1;
    }
    else {
      return $exon if $exon->end() == $start-1;
    }
  }
  return;
}

1;