Bio/Das/SegmentI.pm

   1 #
   2 # BioPerl module for Bio::Das::SegmentI
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Lincoln Stein <lstein@cshl.org>
   7 #
   8 # Copyright Lincoln Stein
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 # POD documentation - main docs before the code
  13
  14 =head1 NAME
  15
  16 Bio::Das::SegmentI - DAS-style access to a feature database
  17
  18 =head1 SYNOPSIS
  19
  20   # Get a Bio::Das::SegmentI object from a Bio::DasI database...
  21
  22   $segment = $das->segment(-name=>'Landmark',
  23                            -start=>$start,
  24                            -end => $end);
  25
  26   @features = $segment->overlapping_features(-type=>['type1','type2']);
  27   # each feature is a Bio::SeqFeatureI-compliant object
  28
  29   @features = $segment->contained_features(-type=>['type1','type2']);
  30
  31   @features = $segment->contained_in(-type=>['type1','type2']);
  32
  33   $stream = $segment->get_feature_stream(-type=>['type1','type2','type3'];
  34   while (my $feature = $stream->next_seq) {
  35      # do something with feature
  36   }
  37
  38   $count = $segment->features_callback(-type=>['type1','type2','type3'],
  39                                        -callback => sub { ... { }
  40                                        );
  41
  42 =head1 DESCRIPTION
  43
  44 Bio::Das::SegmentI is a simplified alternative interface to sequence
  45 annotation databases used by the distributed annotation system. In
  46 this scheme, the genome is represented as a series of landmarks.  Each
  47 Bio::Das::SegmentI object ("segment") corresponds to a genomic region
  48 defined by a landmark and a start and end position relative to that
  49 landmark.  A segment is created using the Bio::DasI segment() method.
  50
  51 Features can be filtered by the following attributes:
  52
  53   1) their location relative to the segment (whether overlapping,
  54           contained within, or completely containing)
  55
  56   2) their type
  57
  58   3) other attributes using tag/value semantics
  59
  60 Access to the feature list uses three distinct APIs:
  61
  62   1) fetching entire list of features at a time
  63
  64   2) fetching an iterator across features
  65
  66   3) a callback
  67
  68 =head1 FEEDBACK
  69
  70 =head2 Mailing Lists
  71
  72 User feedback is an integral part of the evolution of this and other
  73 Bioperl modules. Send your comments and suggestions preferably to one
  74 of the Bioperl mailing lists.  Your participation is much appreciated.
  75
  76   bioperl-l@bio.perl.org
  77
  78 =head2 Support
  79
  80 Please direct usage questions or support issues to the mailing list:
  81
  82 I<bioperl-l@bioperl.org>
  83
  84 rather than to the module maintainer directly. Many experienced and
  85 reponsive experts will be able look at the problem and quickly
  86 address it. Please include a thorough description of the problem
  87 with code and data examples if at all possible.
  88
  89 =head2 Reporting Bugs
  90
  91 Report bugs to the Bioperl bug tracking system to help us keep track
  92 the bugs and their resolution.  Bug reports can be submitted via the
  93 web:
  94
  95   https://github.com/bioperl/bioperl-live/issues
  96
  97 =head1 AUTHOR - Lincoln Stein
  98
  99 Email lstein@cshl.org
 100
 101 =head1 APPENDIX
 102
 103 The rest of the documentation details each of the object
 104 methods. Internal methods are usually preceded with a _
 105
 106 =cut
 107
 108 #'
 109 # Let the code begin...
 110
 111 package Bio::Das::SegmentI;
 112 use strict;
 113
 114
 115 # Object preamble - inherits from Bio::Root::RootI;
 116 use base qw(Bio::Root::RootI);
 117
 118 =head2 seq_id
 119
 120  Title   : seq_id
 121  Usage   : $ref = $s->seq_id
 122  Function: return the ID of the landmark
 123  Returns : a string
 124  Args    : none
 125  Status  : Public
 126
 127 =cut
 128
 129 sub seq_id { shift->throw_not_implemented }
 130
 131 =head2 display_name
 132
 133  Title   : seq_name
 134  Usage   : $ref = $s->seq_name
 135  Function: return the human-readable name for the landmark
 136  Returns : a string
 137  Args    : none
 138  Status  : Public
 139
 140 This defaults to the same as seq_id.
 141
 142 =cut
 143
 144 sub display_name { shift->seq_id }
 145
 146 =head2 start
 147
 148  Title   : start
 149  Usage   : $s->start
 150  Function: start of segment
 151  Returns : integer
 152  Args    : none
 153  Status  : Public
 154
 155 This is a read-only accessor for the start of the segment.  Alias
 156 to low() for Gadfly compatibility.
 157
 158 =cut
 159
 160 sub start  { shift->throw_not_implemented }
 161 sub low    { shift->start }
 162
 163 =head2 end
 164
 165  Title   : end
 166  Usage   : $s->end
 167  Function: end of segment
 168  Returns : integer
 169  Args    : none
 170  Status  : Public
 171
 172 This is a read-only accessor for the end of the segment. Alias to
 173 high() for Gadfly compatibility.
 174
 175 =cut
 176
 177 sub end   { shift->throw_not_implemented  }
 178 sub stop  { shift->end }
 179 sub high  { shift->end }
 180
 181 =head2 length
 182
 183  Title   : length
 184  Usage   : $s->length
 185  Function: length of segment
 186  Returns : integer
 187  Args    : none
 188  Status  : Public
 189
 190 Returns the length of the segment.  Always a positive number.
 191
 192 =cut
 193
 194 sub length { shift->throw_not_implemented; }
 195
 196 =head2 seq
 197
 198  Title   : seq
 199  Usage   : $s->seq
 200  Function: get the sequence string for this segment
 201  Returns : a string
 202  Args    : none
 203  Status  : Public
 204
 205 Returns the sequence for this segment as a simple string.
 206
 207 =cut
 208
 209 sub seq {shift->throw_not_implemented}
 210
 211 =head2 ref
 212
 213  Title   : ref
 214  Usage   : $ref = $s->ref([$newlandmark])
 215  Function: get/set the reference landmark for addressing
 216  Returns : a string
 217  Args    : none
 218  Status  : Public
 219
 220 This method is used to examine/change the reference landmark used to
 221 establish the coordinate system.  By default, the landmark cannot be
 222 changed and therefore this has the same effect as seq_id().  The new
 223 landmark might be an ID, or another Das::SegmentI object.
 224
 225 =cut
 226
 227 sub ref    { shift->seq_id }
 228 *refseq = \&ref;
 229
 230 =head2 absolute
 231
 232  Title   : absolute
 233  Usage   : $s->absolute([$new_value])
 234  Function: get/set absolute addressing mode
 235  Returns : flag
 236  Args    : new flag (optional)
 237  Status  : Public
 238
 239 Turn on and off absolute-addressing mode.  In absolute addressing
 240 mode, coordinates are relative to some underlying "top level"
 241 coordinate system (such as a chromosome). ref() returns the identity
 242 of the top level landmark, and start() and end() return locations
 243 relative to that landmark.  In relative addressing mode, coordinates
 244 are relative to the landmark sequence specified at the time of segment
 245 creation or later modified by the ref() method.
 246
 247 The default is to return false and to do nothing in response to
 248 attempts to set absolute addressing mode.
 249
 250 =cut
 251
 252 sub absolute { return }
 253
 254 =head2 features
 255
 256  Title   : features
 257  Usage   : @features = $s->features(@args)
 258  Function: get features that overlap this segment
 259  Returns : a list of Bio::SeqFeatureI objects
 260  Args    : see below
 261  Status  : Public
 262
 263 This method will find all features that intersect the segment in a
 264 variety of ways and return a list of Bio::SeqFeatureI objects.  The
 265 feature locations will use coordinates relative to the reference
 266 sequence in effect at the time that features() was called.
 267
 268 The returned list can be limited to certain types, attributes or
 269 range intersection modes.  Types of range intersection are one of:
 270
 271    "overlaps"      the default
 272    "contains"      return features completely contained within the segment
 273    "contained_in"  return features that completely contain the segment
 274
 275 Two types of argument lists are accepted.  In the positional argument
 276 form, the arguments are treated as a list of feature types.  In the
 277 named parameter form, the arguments are a series of -name=E<gt>value
 278 pairs.
 279
 280   Argument    Description
 281   --------   ------------
 282
 283   -types      An array reference to type names in the format
 284               "method:source"
 285
 286   -attributes A hashref containing a set of attributes to match
 287
 288   -rangetype  One of "overlaps", "contains", or "contained_in".
 289
 290   -iterator   Return an iterator across the features.
 291
 292   -callback   A callback to invoke on each feature
 293
 294 The -attributes argument is a hashref containing one or more
 295 attributes to match against:
 296
 297   -attributes => { Gene => 'abc-1',
 298                    Note => 'confirmed' }
 299
 300 Attribute matching is simple string matching, and multiple attributes
 301 are ANDed together.  More complex filtering can be performed using the
 302 -callback option (see below).
 303
 304 If -iterator is true, then the method returns an object reference that
 305 implements the next_seq() method.  Each call to next_seq() returns a
 306 new Bio::SeqFeatureI object.
 307
 308 If -callback is passed a code reference, the code reference will be
 309 invoked on each feature returned.  The code will be passed two
 310 arguments consisting of the current feature and the segment object
 311 itself, and must return a true value. If the code returns a false
 312 value, feature retrieval will be aborted.
 313
 314 -callback and -iterator are mutually exclusive options.  If -iterator
 315 is defined, then -callback is ignored.
 316
 317 NOTE: the following methods all build on top of features(), and do not
 318 need to be explicitly implemented.
 319
 320     overlapping_features()
 321     contained_features()
 322     contained_in()
 323     get_feature_stream()
 324
 325 =cut
 326
 327 sub features {shift->throw_not_implemented}
 328
 329 =head2 overlapping_features
 330
 331  Title   : overlapping_features
 332  Usage   : @features = $s->overlapping_features(@args)
 333  Function: get features that overlap this segment
 334  Returns : a list of Bio::SeqFeatureI objects
 335  Args    : see below
 336  Status  : Public
 337
 338 This method is identical to features() except that it defaults to
 339 finding overlapping features.
 340
 341 =cut
 342
 343 sub overlapping_features {
 344   my $self = shift;
 345   my @args = $_[0] =~ /^-/ ? (@_,         -rangetype=>'overlaps')
 346                            : (-types=>\@_,-rangetype=>'overlaps');
 347   $self->features(@args);
 348 }
 349
 350 =head2 contained_features
 351
 352  Title   : contained_features
 353  Usage   : @features = $s->contained_features(@args)
 354  Function: get features that are contained in this segment
 355  Returns : a list of Bio::SeqFeatureI objects
 356  Args    : see below
 357  Status  : Public
 358
 359 This method is identical to features() except that it defaults to
 360 a range type of 'contained'.
 361
 362 =cut
 363
 364 sub contained_features {
 365   my $self = shift;
 366   my @args = $_[0] =~ /^-/ ? (@_,         -rangetype=>'contained')
 367                            : (-types=>\@_,-rangetype=>'contained');
 368   $self->features(@args);
 369 }
 370
 371 =head2 contained_in
 372
 373  Title   : contained_in
 374  Usage   : @features = $s->contained_in(@args)
 375  Function: get features that contain this segment
 376  Returns : a list of Bio::SeqFeatureI objects
 377  Args    : see below
 378  Status  : Public
 379
 380 This method is identical to features() except that it defaults to
 381 a range type of 'contained_in'.
 382
 383 =cut
 384
 385 sub contained_in {
 386   my $self = shift;
 387   my @args = $_[0] =~ /^-/ ? (@_,         -rangetype=>'contained_in')
 388                            : (-types=>\@_,-rangetype=>'contained_in');
 389   $self->features(@args);
 390 }
 391
 392 =head2 get_feature_stream
 393
 394  Title   : get_feature_stream
 395  Usage   : $iterator = $s->get_feature_stream(@args)
 396  Function: get an iterator across the segment
 397  Returns : an object that implements next_seq()
 398  Args    : see below
 399  Status  : Public
 400
 401 This method is identical to features() except that it always generates
 402 an iterator.
 403
 404 NOTE: This is defined in the interface in terms of features().  You do not
 405 have to implement it.
 406
 407 =cut
 408
 409 sub get_feature_stream {
 410   my $self = shift;
 411   my @args = defined $_[0] && $_[0] =~ /^-/ ? (@_,         -iterator=>1)
 412                                             : (-types=>\@_,-iterator=>1);
 413   $self->features(@args);
 414 }
 415
 416 =head2 factory
 417
 418  Title   : factory
 419  Usage   : $factory = $s->factory
 420  Function: return the segment factory
 421  Returns : a Bio::DasI object
 422  Args    : see below
 423  Status  : Public
 424
 425 This method returns a Bio::DasI object that can be used to fetch
 426 more segments.  This is typically the Bio::DasI object from which
 427 the segment was originally generated.
 428
 429 =cut
 430
 431 #'
 432
 433 sub factory {shift->throw_not_implemented}
 434
 435 =head2 primary_tag
 436
 437  Title   : primary_tag
 438  Usage   : $tag = $s->primary_tag
 439  Function: identifies the segment as type "DasSegment"
 440  Returns : a string named "DasSegment"
 441  Args    : none
 442  Status  : Public, but see below
 443
 444 This method provides Bio::Das::Segment objects with a primary_tag()
 445 field that identifies them as being of type "DasSegment".  This allows
 446 the Bio::Graphics engine to render segments just like a feature in order
 447 nis way useful.
 448
 449 This does not need to be implemented.  It is defined by the interface.
 450
 451 =cut
 452
 453 #'
 454
 455 sub primary_tag {"DasSegment"}
 456
 457 =head2 strand
 458
 459  Title   : strand
 460  Usage   : $strand = $s->strand
 461  Function: identifies the segment strand as 0
 462  Returns : the number 0
 463  Args    : none
 464  Status  : Public, but see below
 465
 466 This method provides Bio::Das::Segment objects with a strand() field
 467 that identifies it as being strandless.  This allows the Bio::Graphics
 468 engine to render segments just like a feature in order nis way useful.
 469
 470 This does not need to be implemented.  It is defined by the interface.
 471
 472 =cut
 473
 474 sub strand      { 0 }
 475
 476 1;