Bio/Location/SplitLocationI.pm

   1 #
   2 # BioPerl module for Bio::Location::SplitLocationI
   3 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   4 #
   5 # Cared for by Jason Stajich <jason@bioperl.org>
   6 #
   7 # Copyright Jason Stajich
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10 # POD documentation - main docs before the code
  11
  12 =head1 NAME
  13
  14 Bio::Location::SplitLocationI - Abstract interface of a Location on a Sequence
  15 which has multiple locations (start/end points)
  16
  17 =head1 SYNOPSIS
  18
  19   # get a SplitLocationI somehow
  20     print $splitlocation->start, "..", $splitlocation->end, "\n";
  21     my @sublocs = $splitlocation->sub_Location();
  22
  23     my $count = 1;
  24     # print the start/end points of the sub locations
  25     foreach my $location ( sort { $a->start <=> $b->start }  @sublocs ) {
  26                 printf "sub feature %d [%d..%d]\n", $location->start,$location->end;
  27         $count++;
  28     }
  29
  30 =head1 DESCRIPTION
  31
  32 This interface encapsulates the necessary methods for representing the
  33 location of a sequence feature that has more that just a single
  34 start/end pair.  Some examples of this are the annotated exons in a
  35 gene or the annotated CDS in a sequence file.
  36
  37 =head1 FEEDBACK
  38
  39 User feedback is an integral part of the evolution of this and other
  40 Bioperl modules. Send your comments and suggestions preferably to one
  41 of the Bioperl mailing lists.  Your participation is much appreciated.
  42
  43   bioperl-l@bioperl.org                  - General discussion
  44   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  45
  46 =head2 Support
  47
  48 Please direct usage questions or support issues to the mailing list:
  49
  50 I<bioperl-l@bioperl.org>
  51
  52 rather than to the module maintainer directly. Many experienced and
  53 reponsive experts will be able look at the problem and quickly
  54 address it. Please include a thorough description of the problem
  55 with code and data examples if at all possible.
  56
  57 =head2 Reporting Bugs
  58
  59 Report bugs to the Bioperl bug tracking system to help us keep track
  60 the bugs and their resolution.  Bug reports can be submitted via the
  61 web:
  62
  63   https://github.com/bioperl/bioperl-live/issues
  64
  65 =head1 AUTHOR - Jason Stajich
  66
  67 Email jason-at-bioperl-dot-org
  68
  69 =head1 APPENDIX
  70
  71 The rest of the documentation details each of the object
  72 methods. Internal methods are usually preceded with a _
  73
  74 =cut
  75
  76 # Let the code begin...
  77
  78
  79 package Bio::Location::SplitLocationI;
  80 use strict;
  81
  82 use Carp;
  83
  84 use base qw(Bio::LocationI);
  85
  86
  87 =head2 sub_Location
  88
  89  Title   : sub_Location
  90  Usage   : @locations = $feat->sub_Location();
  91  Function: Returns an array of LocationI objects
  92  Returns : An array
  93  Args    : none
  94
  95 =cut
  96
  97 sub sub_Location {
  98     my ($self,@args) = @_;
  99     $self->throw_not_implemented();
 100 }
 101
 102 =head2 splittype
 103
 104   Title   : splittype
 105   Usage   : $splittype = $fuzzy->splittype();
 106   Function: get/set the split splittype
 107   Returns : the splittype of split feature (join, order)
 108   Args    : splittype to set
 109
 110 =cut
 111
 112 sub splittype {
 113     my($self) = @_;
 114     $self->throw_not_implemented();
 115 }
 116
 117
 118 =head2 is_single_sequence
 119
 120   Title   : is_single_sequence
 121   Usage   : if($splitloc->is_single_sequence()) {
 122                 print "Location object $splitloc is split ".
 123                       "but only across a single sequence\n";
 124             }
 125   Function: Determine whether this location is split across a single or
 126             multiple sequences.
 127   Returns : TRUE if all sublocations lie on the same sequence as the root
 128             location (feature), and FALSE otherwise.
 129   Args    : none
 130
 131 =cut
 132
 133 sub is_single_sequence {
 134     my ($self) = @_;
 135     $self->throw_not_implemented();
 136 }
 137
 138 =head1 Bio::LocationI methods
 139
 140 Bio::LocationI inherited methods follow
 141
 142 =head2 min_start
 143
 144   Title   : min_start
 145   Usage   : my $minstart = $location->min_start();
 146   Function: Get minimum starting location of feature startpoint
 147   Returns : integer or undef if no maximum starting point.
 148   Args    : none
 149
 150 =cut
 151
 152 =head2 max_start
 153
 154   Title   : max_start
 155   Usage   : my $maxstart = $location->max_start();
 156   Function: Get maximum starting location of feature startpoint
 157   Returns : integer or undef if no maximum starting point.
 158   Args    : none
 159
 160 =cut
 161
 162 =head2 start_pos_type
 163
 164   Title   : start_pos_type
 165   Usage   : my $start_pos_type = $location->start_pos_type();
 166   Function: Get start position type (ie <,>, ^)
 167   Returns : type of position coded as text
 168             ('BEFORE', 'AFTER', 'EXACT','WITHIN', 'BETWEEN')
 169   Args    : none
 170
 171 =cut
 172
 173 =head2 min_end
 174
 175   Title   : min_end
 176   Usage   : my $minend = $location->min_end();
 177   Function: Get minimum ending location of feature endpoint
 178   Returns : integer or undef if no minimum ending point.
 179   Args    : none
 180
 181 =cut
 182
 183 =head2 max_end
 184
 185   Title   : max_end
 186   Usage   : my $maxend = $location->max_end();
 187   Function: Get maximum ending location of feature endpoint
 188   Returns : integer or undef if no maximum ending point.
 189   Args    : none
 190
 191 =cut
 192
 193 =head2 end_pos_type
 194
 195   Title   : end_pos_type
 196   Usage   : my $end_pos_type = $location->end_pos_type();
 197   Function: Get end position type (ie <,>, ^)
 198   Returns : type of position coded as text
 199             ('BEFORE', 'AFTER', 'EXACT','WITHIN', 'BETWEEN')
 200   Args    : none
 201
 202 =cut
 203
 204 =head2 seq_id
 205
 206   Title   : seq_id
 207   Usage   : my $seqid = $location->seq_id();
 208   Function: Get/Set seq_id that location refers to
 209   Returns : seq_id
 210   Args    : [optional] seq_id value to set
 211
 212 =cut
 213
 214 =head2 coordinate_policy
 215
 216   Title   : coordinate_policy
 217   Usage   : $policy = $location->coordinate_policy();
 218             $location->coordinate_policy($mypolicy); # set may not be possible
 219   Function: Get the coordinate computing policy employed by this object.
 220
 221             See Bio::Location::CoordinatePolicyI for documentation about
 222             the policy object and its use.
 223
 224             The interface *does not* require implementing classes to accept
 225             setting of a different policy. The implementation provided here
 226             does, however, allow to do so.
 227
 228             Implementors of this interface are expected to initialize every
 229             new instance with a CoordinatePolicyI object. The implementation
 230             provided here will return a default policy object if none has
 231             been set yet. To change this default policy object call this
 232             method as a class method with an appropriate argument. Note that
 233             in this case only subsequently created Location objects will be
 234             affected.
 235
 236   Returns : A Bio::Location::CoordinatePolicyI implementing object.
 237   Args    : On set, a Bio::Location::CoordinatePolicyI implementing object.
 238
 239 =cut
 240
 241 =head2 to_FTstring
 242
 243   Title   : to_FTstring
 244   Usage   : my $locstr = $location->to_FTstring()
 245   Function: returns the FeatureTable string of this location
 246   Returns : string
 247   Args    : none
 248
 249 =cut
 250
 251 1;
 252