Bio/Seq/MetaI.pm

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