lib/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
 164 use strict;
 165
 166 use base qw(Bio::Root::RootI);
 167
 168 =head2 meta
 169
 170  Title   : meta
 171  Usage   : $meta_values  = $obj->meta($values_string);
 172  Function:
 173
 174            Get and set method for the unnamed meta data starting from
 175            residue position one. Since it is dependent on the length
 176            of the sequence, it needs to be manipulated after the
 177            sequence.
 178
 179            The implementation may choose to accept argument values in
 180            a string or in an array (reference) or in a hash
 181            (reference).
 182
 183            The return value may be a string or an array reference,
 184            depending on the implementation. If in doubt, use meta_text()
 185            which is a variant guarantied to return a string.  See
 186            L<meta_text>.
 187
 188            The length of the returned value always matches the length
 189            of the sequence.
 190
 191  Returns : A reference to an array or a string
 192  Args    : new value, optional
 193
 194 =cut
 195
 196 sub meta { shift->throw_not_implemented }
 197
 198 =head2 meta_text
 199
 200  Title   : meta_text()
 201  Usage   : $meta_values  = $obj->meta_text($values_arrayref);
 202  Function: Variant of meta() guarantied to return a textual
 203            representation of the meta data. For details, see L<meta>.
 204  Returns : a string
 205  Args    : new value, optional
 206
 207 =cut
 208
 209 sub meta_text { shift->throw_not_implemented }
 210
 211 =head2 named_meta
 212
 213  Title   : named_meta()
 214  Usage   : $meta_values  = $obj->named_meta($name, $values_arrayref);
 215  Function: A more general version of meta(). Each meta data set needs
 216            to be named. See also L<meta_names>.
 217  Returns : a string
 218  Args    : scalar, name of the meta data set
 219            new value, optional
 220
 221 =cut
 222
 223 sub named_meta { shift->throw_not_implemented }
 224
 225 =head2 named_meta_text
 226
 227  Title   : named_meta_text()
 228  Usage   : $meta_values  = $obj->named_meta_text($name, $values_arrayref);
 229  Function: Variant of named_meta() guarantied to return a textual
 230            representation  of the named meta data.
 231            For details, see L<meta>.
 232  Returns : a string
 233  Args    : scalar, name of the meta data set
 234            new value, optional
 235
 236 =cut
 237
 238 sub named_meta_text { shift->throw_not_implemented }
 239
 240 =head2 submeta
 241
 242  Title   : submeta
 243  Usage   : $subset_of_meta_values = $obj->submeta(10, 20, $value_string);
 244            $subset_of_meta_values = $obj->submeta(10, undef, $value_string);
 245  Function:
 246
 247            Get and set method for meta data for subsequences.
 248
 249            Numbering starts from 1 and the number is inclusive, ie 1-2
 250            are the first two residue of the sequence. Start cannot be
 251            larger than end but can be equal.
 252
 253            If the second argument is missing the returned values
 254            should extend to the end of the sequence.
 255
 256            If implementation tries to set values beyond the current
 257            sequence, they should be ignored.
 258
 259            The return value may be a string or an array reference,
 260            depending on the implementation. If in doubt, use
 261            submeta_text() which is a variant guarantied to return a
 262            string.  See L<submeta_text>.
 263
 264  Returns : A reference to an array or a string
 265  Args    : integer, start position, optional
 266            integer, end position, optional
 267            new value, optional
 268
 269 =cut
 270
 271 sub submeta { shift->throw_not_implemented }
 272
 273 =head2 submeta_text
 274
 275  Title   : submeta_text
 276  Usage   : $meta_values  = $obj->submeta_text(20, $value_string);
 277  Function: Variant of submeta() guarantied to return a textual
 278            representation  of meta data. For details, see L<meta>.
 279  Returns : a string
 280  Args    : integer, start position, optional
 281            integer, end position, optional
 282            new value, optional
 283
 284 =cut
 285
 286 sub submeta_text { shift->throw_not_implemented }
 287
 288 =head2 named_submeta
 289
 290  Title   : named_submeta
 291  Usage   : $subset_of_meta_values = $obj->named_submeta($name, 10, 20, $value_string);
 292            $subset_of_meta_values = $obj->named_submeta($name, 10);
 293  Function: Variant of submeta() guarantied to return a textual
 294            representation  of meta data. For details, see L<meta>.
 295  Returns : A reference to an array or a string
 296  Args    : scalar, name of the meta data set
 297            integer, start position
 298            integer, end position, optional when a third argument present
 299            new value, optional
 300
 301 =cut
 302
 303 sub named_submeta { shift->throw_not_implemented }
 304
 305 =head2 named_submeta_text
 306
 307  Title   : named_submeta_text
 308  Usage   : $meta_values  = $obj->named_submeta_text($name, 20, $value_string);
 309  Function: Variant of submeta() guarantied to return a textual
 310            representation  of meta data. For details, see L<meta>.
 311  Returns : a string
 312  Args    : scalar, name of the meta data
 313  Args    : integer, start position, optional
 314            integer, end position, optional
 315            new value, optional
 316
 317 =cut
 318
 319 sub named_submeta_text { shift->throw_not_implemented }
 320
 321 =head2 meta_names
 322
 323  Title   : meta_names
 324  Usage   : @meta_names  = $obj->meta_names()
 325  Function: Retrieves an array of meta data set names. The default (unnamed)
 326            set name is guarantied to be the first name.
 327  Returns : an array of names
 328  Args    : none
 329
 330 =cut
 331
 332 sub meta_names { shift->throw_not_implemented }
 333
 334
 335 =head2 force_flush
 336
 337  Title   : force_flush()
 338  Usage   : $force_flush = $obj->force_flush(1);
 339  Function: Automatically pad with empty values or truncate meta values to
 340             sequence length
 341  Returns : boolean 1 or 0
 342  Args    : optional boolean value
 343
 344 =cut
 345
 346 sub force_flush { shift->throw_not_implemented }
 347
 348
 349 =head2 is_flush
 350
 351  Title   : is_flush
 352  Usage   : $is_flush  = $obj->is_flush()
 353            or  $is_flush = $obj->is_flush($my_meta_name)
 354  Function: Boolean to tell if all meta values are in
 355            flush with the sequence length.
 356            Returns true if force_flush() is set
 357            Set verbosity to a positive value to see failed meta sets
 358  Returns : boolean 1 or 0
 359  Args    : optional name of the meta set
 360
 361 =cut
 362
 363 sub is_flush { shift->throw_not_implemented }
 364
 365
 366 =head2 meta_length
 367
 368  Title   : meta_length()
 369  Usage   : $meeta_len  = $obj->meta_length();
 370  Function: return the number of elements in the meta set
 371  Returns : integer
 372  Args    : -
 373
 374 =cut
 375
 376 sub meta_length { shift->throw_not_implemented }
 377
 378 =head2 named_meta_length
 379
 380  Title   : named_meta_length()
 381  Usage   : $meeta_len  = $obj->named_meta_length($name);
 382  Function: return the number of elements in the named meta set
 383  Returns : integer
 384  Args    : -
 385
 386 =cut
 387
 388 sub named_meta_length { shift->throw_not_implemented }
 389
 390
 391 =head1 Bio::PrimarySeqI methods
 392
 393 Implementing classes will need to rewrite these Bio::PrimaryI methods.
 394
 395 =cut
 396
 397 =head2 revcom
 398
 399  Title   : revcom
 400  Usage   : $newseq = $seq->revcom();
 401  Function: Produces a new Bio::Seq::MetaI implementing object where
 402            the order of residues and their meta information is reversed.
 403  Returns : A new (fresh) Bio::Seq::MetaI object
 404  Args    : none
 405
 406 =cut
 407
 408 sub revcom { shift->throw_not_implemented }
 409
 410 =head2 trunc
 411
 412  Title   : trunc
 413  Usage   : $subseq = $myseq->trunc(10,100);
 414  Function: Provides a truncation of a sequence
 415  Returns : a fresh Bio::Seq::MetaI implementing object
 416  Args    : Two integers denoting first and last residue of the sub-sequence.
 417
 418 =cut
 419
 420 sub trunc { shift->throw_not_implemented }
 421
 422
 423 1;