Bio/Seq/MetaI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Seq::MetaI
   4 #
   5 # Cared for by Heikki Lehvaslaiho
   6 #
   7 # Copyright Heikki Lehvaslaiho
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::Seq::MetaI - Interface for sequence objects with residue-based
  16 meta information
  17
  18 =head1 SYNOPSIS
  19
  20   # get a Bio::Seq::MetaI compliant object somehow
  21
  22   # to test this is a meta seq object
  23   $obj->isa("Bio::Seq::MetaI")
  24      || $obj->throw("$obj not a Bio::Seq::MetaI");
  25
  26   # accessors
  27   $string     = $obj->meta;
  28   $string     = $obj->meta_text;
  29   $substring  = $obj->submeta(12,50);
  30   $unique_key = $obj->accession_number();
  31
  32
  33 =head1 DESCRIPTION
  34
  35 This class defines an abstract interface for basic residue-based meta
  36 information. Examples of this kind of meta data are secondary
  37 structures (RNA and protein), protein hydrophobicity assignments, or
  38 other alternative alphabets for polypeptides, sequence quality data
  39 and nucleotide alignments with translations.
  40
  41 The length of the meta data sequence is not dependent on the amount of
  42 the meta information. The meta information always covers all the
  43 residues, but a blank value is used to denote unavailable
  44 information. If necessary the implementation quietly truncates or
  45 extends meta information with blank values. Definition of blank is
  46 implementation dependent. Gaps in MSAs should not have meta
  47 information.
  48
  49 At this point a residue in a sequence object can have only one meta
  50 value. If you need more, use multiple copies of the sequence object.
  51
  52 Meta data storage can be implemented in various ways, e.g: string,
  53 array of scalars, array of hashes, array of objects.
  54
  55 If the implementation so chooses, there can be more then one meta
  56 values associated to each residue. See L<named_meta> and
  57 L<names_submeta>. Note that use of arbitrary names is very prone to
  58 typos leading to creation of additional copies of meta data sets.
  59
  60 Bio::Seq::Meta provides basic, pure perl implementation of sequences
  61 with meta information. See L<Bio::Seq::Meta>. Application specific
  62 implementations will override and add to these methods.
  63
  64 =head2 Method naming
  65
  66 Character based meta data is read and set by method meta() and its
  67 variants. These are the suffixes and prefixes used in the variants:
  68
  69     [named_] [sub] meta [_text]
  70
  71 =over 3
  72
  73 =item _text
  74
  75 Suffix B<_text> guaranties that output is a string. Note that it does
  76 not limit the input.
  77
  78 =item sub
  79
  80 Prefix B<sub>, like in subseq(), means that the method applies to sub
  81 region of the sequence range and takes start and end as arguments.
  82 Unlike subseq(), these methods are able to set values.  If the range
  83 is not defined, it defaults to the complete sequence.
  84
  85 =item named_
  86
  87 Prefix B<named_> in method names allows the used to attach multiple
  88 meta strings to one sequence by explicitly naming them. The name is
  89 always the first argument to the method. The "unnamed" methods use the
  90 class wide default name for the meta data and are thus special cases
  91 "named" methods.
  92
  93 Note that internally names are keys in a hash and any misspelling of a
  94 name will silently store the data under a wrong name. The used names
  95 (keys) can be retrieved using method meta_names(). See L<meta_names>.
  96
  97 =back
  98
  99
 100 =head1 SEE ALSO
 101
 102 L<Bio::Seq::Meta>,
 103 L<Bio::Seq::Meta::Array>,
 104 L<Bio::Seq::EncodedSeq>,
 105 L<Bio::Tools::OddCodes>,
 106 L<Bio::Seq::Quality>
 107
 108
 109 =head1 FEEDBACK
 110
 111 =head2 Mailing Lists
 112
 113 User feedback is an integral part of the evolution of this and other
 114 Bioperl modules. Send your comments and suggestions preferably to one
 115 of the Bioperl mailing lists.  Your participation is much appreciated.
 116
 117   bioperl-l@bioperl.org                  - General discussion
 118   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
 119
 120 =head2 Reporting Bugs
 121
 122 Report bugs to the Bioperl bug tracking system to help us keep track
 123 the bugs and their resolution.  Bug reports can be submitted via the
 124 web:
 125
 126   http://bugzilla.open-bio.org/
 127
 128 =head1 AUTHOR - Heikki Lehvaslaiho
 129
 130 Email heikki-at-bioperl-dot-org
 131
 132 =head1 CONTRIBUTORS
 133
 134 Chad Matsalla, bioinformatics@dieselwurks.com;
 135 Aaron Mackey, amackey@virginia.edu;
 136 Peter Schattner schattner@alum.mit.edu;
 137 Richard Adams, Richard.Adams@ed.ac.uk
 138
 139 =head1 APPENDIX
 140
 141 The rest of the documentation details each of the object methods.
 142 Internal methods are usually preceded with a _
 143
 144 =cut
 145
 146
 147 # Let the code begin...
 148
 149
 150 package Bio::Seq::MetaI;
 151 use strict;
 152
 153 use base qw(Bio::Root::RootI);
 154
 155 =head2 meta
 156
 157  Title   : meta
 158  Usage   : $meta_values  = $obj->meta($values_string);
 159  Function:
 160
 161            Get and set method for the unnamed meta data starting from
 162            residue position one. Since it is dependent on the length
 163            of the sequence, it needs to be manipulated after the
 164            sequence.
 165
 166            The implementation may choose to accept argument values in
 167            a string or in an array (reference) or in a hash
 168            (reference).
 169
 170            The return value may be a string or an array reference,
 171            depending on the implentation. If in doubt, use meta_text()
 172            which is a variant guarantied to return a string.  See
 173            L<meta_text>.
 174
 175            The length of the returned value always matches the length
 176            of the sequence.
 177
 178  Returns : A reference to an array or a string
 179  Args    : new value, optional
 180
 181 =cut
 182
 183 sub meta { shift->throw_not_implemented }
 184
 185 =head2 meta_text
 186
 187  Title   : meta_text()
 188  Usage   : $meta_values  = $obj->meta_text($values_arrayref);
 189  Function: Variant of meta() guarantied to return a textual
 190            representation of the meta data. For details, see L<meta>.
 191  Returns : a string
 192  Args    : new value, optional
 193
 194 =cut
 195
 196 sub meta_text { shift->throw_not_implemented }
 197
 198 =head2 named_meta
 199
 200  Title   : named_meta()
 201  Usage   : $meta_values  = $obj->named_meta($name, $values_arrayref);
 202  Function: A more general version of meta(). Each meta data set needs
 203            to be named. See also L<meta_names>.
 204  Returns : a string
 205  Args    : scalar, name of the meta data set
 206            new value, optional
 207
 208 =cut
 209
 210 sub named_meta { shift->throw_not_implemented }
 211
 212 =head2 named_meta_text
 213
 214  Title   : named_meta_text()
 215  Usage   : $meta_values  = $obj->named_meta_text($name, $values_arrayref);
 216  Function: Variant of named_meta() guarantied to return a textual
 217            representation  of the named meta data.
 218            For details, see L<meta>.
 219  Returns : a string
 220  Args    : scalar, name of the meta data set
 221            new value, optional
 222
 223 =cut
 224
 225 sub named_meta_text { shift->throw_not_implemented }
 226
 227 =head2 submeta
 228
 229  Title   : submeta
 230  Usage   : $subset_of_meta_values = $obj->submeta(10, 20, $value_string);
 231            $subset_of_meta_values = $obj->submeta(10, undef, $value_string);
 232  Function:
 233
 234            Get and set method for meta data for subsequences.
 235
 236            Numbering starts from 1 and the number is inclusive, ie 1-2
 237            are the first two residue of the sequence. Start cannot be
 238            larger than end but can be equal.
 239
 240            If the second argument is missing the returned values
 241            should extend to the end of the sequence.
 242
 243            If implementation tries to set values beyond the current
 244            sequence, they should be ignored.
 245
 246            The return value may be a string or an array reference,
 247            depending on the implentation. If in doubt, use
 248            submeta_text() which is a variant guarantied to return a
 249            string.  See L<submeta_text>.
 250
 251  Returns : A reference to an array or a string
 252  Args    : integer, start position, optional
 253            integer, end position, optional
 254            new value, optional
 255
 256 =cut
 257
 258 sub submeta { shift->throw_not_implemented }
 259
 260 =head2 submeta_text
 261
 262  Title   : submeta_text
 263  Usage   : $meta_values  = $obj->submeta_text(20, $value_string);
 264  Function: Variant of submeta() guarantied to return a textual
 265            representation  of meta data. For details, see L<meta>.
 266  Returns : a string
 267  Args    : integer, start position, optional
 268            integer, end position, optional
 269            new value, optional
 270
 271 =cut
 272
 273 sub submeta_text { shift->throw_not_implemented }
 274
 275 =head2 named_submeta
 276
 277  Title   : named_submeta
 278  Usage   : $subset_of_meta_values = $obj->named_submeta($name, 10, 20, $value_string);
 279            $subset_of_meta_values = $obj->named_submeta($name, 10);
 280  Function: Variant of submeta() guarantied to return a textual
 281            representation  of meta data. For details, see L<meta>.
 282  Returns : A reference to an array or a string
 283  Args    : scalar, name of the meta data set
 284            integer, start position
 285            integer, end position, optional when a third argument present
 286            new value, optional
 287
 288 =cut
 289
 290 sub named_submeta { shift->throw_not_implemented }
 291
 292 =head2 named_submeta_text
 293
 294  Title   : named_submeta_text
 295  Usage   : $meta_values  = $obj->named_submeta_text($name, 20, $value_string);
 296  Function: Variant of submeta() guarantied to return a textual
 297            representation  of meta data. For details, see L<meta>.
 298  Returns : a string
 299  Args    : scalar, name of the meta data
 300  Args    : integer, start position, optional
 301            integer, end position, optional
 302            new value, optional
 303
 304 =cut
 305
 306 sub named_submeta_text { shift->throw_not_implemented }
 307
 308 =head2 meta_names
 309
 310  Title   : meta_names
 311  Usage   : @meta_names  = $obj->meta_names()
 312  Function: Retrives an array of meta data set names. The default (unnamed)
 313            set name is guarantied to be the first name.
 314  Returns : an array of names
 315  Args    : none
 316
 317 =cut
 318
 319 sub meta_names { shift->throw_not_implemented }
 320
 321
 322 =head2 force_flush
 323
 324  Title   : force_flush()
 325  Usage   : $force_flush = $obj->force_flush(1);
 326  Function: Automatically pad with empty values or truncate meta values to
 327             sequence length
 328  Returns : boolean 1 or 0
 329  Args    : optional boolean value
 330
 331 =cut
 332
 333 sub force_flush { shift->throw_not_implemented }
 334
 335
 336 =head2 is_flush
 337
 338  Title   : is_flush
 339  Usage   : $is_flush  = $obj->is_flush()
 340            or  $is_flush = $obj->is_flush($my_meta_name)
 341  Function: Boolean to tell if all meta values are in
 342            flush with the sequence length.
 343            Returns true if force_flush() is set
 344            Set verbosity to a positive value to see failed meta sets
 345  Returns : boolean 1 or 0
 346  Args    : optional name of the meta set
 347
 348 =cut
 349
 350 sub is_flush { shift->throw_not_implemented }
 351
 352
 353 =head2 meta_length
 354
 355  Title   : meta_length()
 356  Usage   : $meeta_len  = $obj->meta_length();
 357  Function: return the number of elements in the meta set
 358  Returns : integer
 359  Args    : -
 360
 361 =cut
 362
 363 sub meta_length { shift->throw_not_implemented }
 364
 365 =head2 named_meta_length
 366
 367  Title   : named_meta_length()
 368  Usage   : $meeta_len  = $obj->named_meta_length($name);
 369  Function: return the number of elements in the named meta set
 370  Returns : integer
 371  Args    : -
 372
 373 =cut
 374
 375 sub named_meta_length { shift->throw_not_implemented }
 376
 377
 378 =head1 Bio::PrimarySeqI methods
 379
 380 Implemeting classes will need to rewrite these Bio::PrimaryI methods.
 381
 382 =cut
 383
 384 =head2 revcom
 385
 386  Title   : revcom
 387  Usage   : $newseq = $seq->revcom();
 388  Function: Produces a new Bio::Seq::MetaI implementing object where
 389            the order of residues and their meta information is reversed.
 390  Returns : A new (fresh) Bio::Seq::MetaI object
 391  Args    : none
 392
 393 =cut
 394
 395 sub revcom { shift->throw_not_implemented }
 396
 397 =head2 trunc
 398
 399  Title   : trunc
 400  Usage   : $subseq = $myseq->trunc(10,100);
 401  Function: Provides a truncation of a sequence
 402  Returns : a fresh Bio::Seq::MetaI implementing object
 403  Args    : Two integers denoting first and last residue of the sub-sequence.
 404
 405 =cut
 406
 407 sub trunc { shift->throw_not_implemented }
 408
 409
 410 1;