| 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 | 24 | $Bio::Seq::MetaI::VERSION = '1.7.8'; | |
| 164 | 24 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 165 | |||
| 166 | 24 | ▶ | use base qw(Bio::Root::RootI); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 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 | 0 | ▶ | sub meta { shift->throw_not_implemented } |
|
Subroutine
meta: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub meta_text { shift->throw_not_implemented } |
|
Subroutine
meta_text: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub named_meta { shift->throw_not_implemented } |
|
Subroutine
named_meta: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub named_meta_text { shift->throw_not_implemented } |
|
Subroutine
named_meta_text: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub submeta { shift->throw_not_implemented } |
|
Subroutine
submeta: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub submeta_text { shift->throw_not_implemented } |
|
Subroutine
submeta_text: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub named_submeta { shift->throw_not_implemented } |
|
Subroutine
named_submeta: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub named_submeta_text { shift->throw_not_implemented } |
|
Subroutine
named_submeta_text: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub meta_names { shift->throw_not_implemented } |
|
Subroutine
meta_names: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub force_flush { shift->throw_not_implemented } |
|
Subroutine
force_flush: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub is_flush { shift->throw_not_implemented } |
|
Subroutine
is_flush: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub meta_length { shift->throw_not_implemented } |
|
Subroutine
meta_length: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub named_meta_length { shift->throw_not_implemented } |
|
Subroutine
named_meta_length: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub revcom { shift->throw_not_implemented } |
|
Subroutine
revcom: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 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 | 0 | ▶ | sub trunc { shift->throw_not_implemented } |
|
Subroutine
trunc: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 421 | |||
| 422 | |||
| 423 | 24 | 1; | |