branch-1-6/Bio/Phenotype/PhenotypeI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Phenotype::PhenotypeI
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Christian M. Zmasek <czmasek-at-burnham.org> or <cmzmasek@yahoo.com>
   8 #
   9 # (c) Christian M. Zmasek, czmasek-at-burnham.org, 2002.
  10 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
  11 #
  12 # You may distribute this module under the same terms as perl itself.
  13 # Refer to the Perl Artistic License (see the license accompanying this
  14 # software package, or see http://www.perl.com/language/misc/Artistic.html)
  15 # for the terms under which you may use, modify, and redistribute this module.
  16 #
  17 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  18 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  19 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  20 #
  21 # You may distribute this module under the same terms as perl itself
  22
  23 # POD documentation - main docs before the code
  24
  25 =head1 NAME
  26
  27 Bio::Phenotype::PhenotypeI - An interface for classes modeling phenotypes
  28
  29 =head1 SYNOPSIS
  30
  31   #get Bio::Phenotype::PhenotypeI somehow
  32
  33   print $phenotype->name(), "\n";
  34   print $phenotype->description(), "\n";
  35
  36   my @keywords = ( "achondroplasia", "dwarfism" );
  37   $phenotype->add_keywords( @keywords );
  38   foreach my $keyword ( $phenotype->each_keyword() ) {
  39        print $keyword, "\n";
  40   }
  41   $phenotype->remove_keywords();
  42
  43
  44   foreach my $gene_symbol ( $phenotype->each_gene_symbol() ) {
  45        print $gene_symbol, "\n";
  46   }
  47
  48   foreach my $corr ( $phenotype->each_Correlate() ) {
  49        # Do something with $corr
  50   }
  51
  52   foreach my $var ( $phenotype->each_Variant() ) {
  53        # Do something with $var (mutation)
  54   }
  55
  56   foreach my $measure ( $phenotype->each_Measure() ) {
  57        # Do something with $measure
  58   }
  59
  60
  61 =head1 DESCRIPTION
  62
  63 This superclass defines common methods for classes modelling phenotypes.
  64 Bio::Phenotype::OMIM::OMIMentry is an example of an instantiable phenotype
  65 class (the design of this interface was partially guided by the need
  66 to model OMIM entries).
  67 Please note. This interface provides methods to associate mutations
  68 (methods "each_Variant", ...) and genotypes (methods "each_Genotype", ...)
  69 with phenotypes. Yet, these aspects might need some future enhancements,
  70 especially since there is no "genotype" class yet.
  71
  72 =head1 FEEDBACK
  73
  74 =head2 Mailing Lists
  75
  76 User feedback is an integral part of the evolution of this and other
  77 Bioperl modules. Send your comments and suggestions preferably to the
  78 Bioperl mailing lists  Your participation is much appreciated.
  79
  80   bioperl-l@bioperl.org                  - General discussion
  81   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  82
  83 =head2 Support
  84
  85 Please direct usage questions or support issues to the mailing list:
  86
  87 I<bioperl-l@bioperl.org>
  88
  89 rather than to the module maintainer directly. Many experienced and
  90 reponsive experts will be able look at the problem and quickly
  91 address it. Please include a thorough description of the problem
  92 with code and data examples if at all possible.
  93
  94 =head2 Reporting Bugs
  95
  96 report bugs to the Bioperl bug tracking system to help us keep track
  97 the bugs and their resolution.  Bug reports can be submitted via the
  98 web:
  99
 100   http://bugzilla.open-bio.org/
 101
 102 =head1 AUTHOR
 103
 104 Christian M. Zmasek
 105
 106 Email: czmasek-at-burnham.org  or  cmzmasek@yahoo.com
 107
 108 WWW:   http://monochrome-effect.net/
 109
 110 Address:
 111
 112   Genomics Institute of the Novartis Research Foundation
 113   10675 John Jay Hopkins Drive
 114   San Diego, CA 92121
 115
 116 =head1 APPENDIX
 117
 118 The rest of the documentation details each of the object
 119 methods. Internal methods are usually preceded with a _
 120
 121 =cut
 122
 123
 124 # Let the code begin...
 125
 126
 127 package Bio::Phenotype::PhenotypeI;
 128 use base qw(Bio::Root::RootI);
 129
 130
 131
 132 =head2 name
 133
 134  Title   : name
 135  Usage   : $obj->name( "r1" );
 136            or
 137            print $obj->name();
 138  Function: Set/get for the name or id of this phenotype.
 139  Returns : A name or id [scalar].
 140  Args    : A name or id [scalar] (optional).
 141
 142 =cut
 143
 144 sub name {
 145     my ( $self ) = @_;
 146
 147     $self->throw_not_implemented();
 148
 149 } # name
 150
 151
 152
 153
 154 =head2 description
 155
 156  Title   : description
 157  Usage   : $obj->description( "This is ..." );
 158            or
 159            print $obj->description();
 160  Function: Set/get for the description of this phenotype.
 161  Returns : A description [scalar].
 162  Args    : A description [scalar] (optional).
 163
 164 =cut
 165
 166 sub description {
 167      my ( $self ) = @_;
 168
 169     $self->throw_not_implemented();
 170
 171 } # description
 172
 173
 174
 175
 176 =head2 species
 177
 178  Title   : species
 179  Usage   : $obj->species( $species );
 180            or
 181            $species = $obj->species();
 182  Function: Set/get for the species of this phenotype.
 183  Returns : A species [Bio::Species].
 184  Args    : A species [Bio::Species] (optional).
 185
 186 =cut
 187
 188 sub species {
 189     my ( $self ) = @_;
 190
 191     $self->throw_not_implemented();
 192
 193 } # species
 194
 195
 196
 197
 198 =head2 comment
 199
 200  Title   : comment
 201  Usage   : $obj->comment( "putative" );
 202            or
 203            print $obj->comment();
 204  Function: Set/get for a comment about this phenotype.
 205  Returns : A comment [scalar].
 206  Args    : A comment [scalar] (optional).
 207
 208 =cut
 209
 210 sub comment {
 211     my ( $self ) = @_;
 212
 213     $self->throw_not_implemented();
 214
 215 } # comment
 216
 217
 218
 219
 220 =head2 each_gene_symbol
 221
 222  Title   : each_gene_symbol()
 223  Usage   : @gs = $obj->each_gene_symbol();
 224  Function: Returns a list of gene symbols [scalars, most likely Strings]
 225            associated with this phenotype.
 226  Returns : A list of scalars.
 227  Args    :
 228
 229 =cut
 230
 231 sub each_gene_symbol {
 232     my ( $self ) = @_;
 233
 234     $self->throw_not_implemented();
 235
 236 } # each_gene_symbol
 237
 238
 239 =head2 add_gene_symbols
 240
 241  Title   : add_gene_symbols
 242  Usage   : $obj->add_gene_symbols( @gs );
 243            or
 244            $obj->add_gene_symbols( $gs );
 245  Function: Pushes one or more gene symbols [scalars, most likely Strings]
 246            into the list of gene symbols.
 247  Returns :
 248  Args    : scalar(s).
 249
 250 =cut
 251
 252 sub add_gene_symbols {
 253     my ( $self ) = @_;
 254
 255     $self->throw_not_implemented();
 256
 257 } # add_gene_symbols
 258
 259
 260 =head2 remove_gene_symbols
 261
 262  Usage   : $obj->remove_gene_symbols();
 263  Function: Deletes (and returns) the list of gene symbols [scalars,
 264            most likely Strings] associated with this phenotype.
 265  Returns : A list of scalars.
 266  Args    :
 267
 268 =cut
 269
 270 sub remove_gene_symbols {
 271     my ( $self ) = @_;
 272
 273     $self->throw_not_implemented();
 274
 275 } # remove_gene_symbols
 276
 277
 278
 279
 280 =head2 each_Variant
 281
 282  Title   : each_Variant()
 283  Usage   : @vs = $obj->each_Variant();
 284  Function: Returns a list of Bio::Variation::VariantI implementing objects
 285            associated with this phenotype.
 286            This is for representing the actual mutation(s) causing this
 287            phenotype.
 288            {* The "variants" data member and its methods will/might need to be
 289            changed/improved in one way or another, CZ 09/06/02 *}
 290  Returns : A list of Bio::Variation::VariantI implementing objects.
 291  Args    :
 292
 293 =cut
 294
 295 sub each_Variant {
 296     my ( $self ) = @_;
 297
 298     $self->throw_not_implemented();
 299
 300 } # each_Variant
 301
 302
 303 =head2 add_Variants
 304
 305  Usage   : $obj->add_Variants( @vs );
 306            or
 307            $obj->add_Variants( $v );
 308  Function: Pushes one or more Bio::Variation::VariantI implementing objects
 309            into the list of Variants.
 310  Returns :
 311  Args    : Bio::Variation::VariantI implementing object(s).
 312
 313 =cut
 314
 315 sub add_Variants {
 316     my ( $self ) = @_;
 317
 318     $self->throw_not_implemented();
 319
 320 } # add_Variants
 321
 322
 323 =head2 remove_Variants
 324
 325  Title   : remove_Variants
 326  Usage   : $obj->remove_Variants();
 327  Function: Deletes (and returns) the list of Bio::Variation::VariantI implementing
 328            objects associated with this phenotype.
 329  Returns : A list of Bio::Variation::VariantI implementing objects.
 330  Args    :
 331
 332 =cut
 333
 334 sub remove_Variants {
 335     my ( $self ) = @_;
 336
 337     $self->throw_not_implemented();
 338
 339 } # remove_Variants
 340
 341
 342
 343
 344 =head2 each_Reference
 345
 346  Title   : each_Reference()
 347  Usage   : @refs = $obj->each_Reference();
 348  Function: Returns a list of Bio::Annotation::Reference objects
 349            associated with this phenotype.
 350  Returns : A list of Bio::Annotation::Reference objects.
 351  Args    :
 352
 353 =cut
 354
 355 sub each_Reference {
 356     my ( $self ) = @_;
 357
 358     $self->throw_not_implemented();
 359
 360 } # each_Reference
 361
 362
 363 =head2 add_References
 364
 365  Title   : add_References
 366  Usage   : $obj->add_References( @refs );
 367            or
 368            $obj->add_References( $ref );
 369  Function: Pushes one or more Bio::Annotation::Reference objects
 370            into the list of References.
 371  Returns :
 372  Args    : Bio::Annotation::Reference object(s).
 373
 374 =cut
 375
 376 sub add_References {
 377     my ( $self ) = @_;
 378
 379     $self->throw_not_implemented();
 380
 381 } # add_References
 382
 383
 384 =head2 remove_References
 385
 386  Title   : remove_References()
 387  Usage   : $obj->remove_References();
 388  Function: Deletes (and returns) the list of Bio::Annotation::Reference objects
 389            associated with this phenotype.
 390  Returns : A list of Bio::Annotation::Reference objects.
 391  Args    :
 392
 393 =cut
 394
 395 sub remove_References {
 396     my ( $self ) = @_;
 397
 398     $self->throw_not_implemented();
 399
 400 } # remove_References
 401
 402
 403
 404
 405 =head2 each_CytoPosition
 406
 407  Title   : each_CytoPosition()
 408  Usage   : @cps = $obj->each_CytoPosition();
 409  Function: Returns a list of Bio::Map::CytoPosition objects
 410            associated with this phenotype.
 411  Returns : A list of Bio::Map::CytoPosition objects.
 412  Args    :
 413
 414 =cut
 415
 416 sub each_CytoPosition {
 417     my ( $self ) = @_;
 418
 419     $self->throw_not_implemented();
 420
 421 } # each_CytoPosition
 422
 423
 424 =head2 add_CytoPositions
 425
 426  Title   : add_CytoPositions
 427  Usage   : $obj->add_CytoPositions( @cps );
 428            or
 429            $obj->add_CytoPositions( $cp );
 430  Function: Pushes one or more Bio::Map::CytoPosition objects
 431            into the list of CytoPositions.
 432  Returns :
 433  Args    : Bio::Map::CytoPosition object(s).
 434
 435 =cut
 436
 437 sub add_CytoPositions {
 438     my ( $self ) = @_;
 439
 440     $self->throw_not_implemented();
 441
 442 } # add_CytoPositions
 443
 444
 445 =head2 remove_CytoPositions
 446
 447  Title   : remove_CytoPositions
 448  Usage   : $obj->remove_CytoPositions();
 449  Function: Deletes (and returns) the list o fBio::Map::CytoPosition objects
 450            associated with this phenotype.
 451  Returns : A list of Bio::Map::CytoPosition objects.
 452  Args    :
 453
 454 =cut
 455
 456 sub remove_CytoPositions {
 457     my ( $self ) = @_;
 458
 459     $self->throw_not_implemented();
 460
 461 } # remove_CytoPositions
 462
 463
 464
 465
 466 =head2 each_Correlate
 467
 468  Title   : each_Correlate()
 469  Usage   : @corrs = $obj->each_Correlate();
 470  Function: Returns a list of Bio::Phenotype::Correlate objects
 471            associated with this phenotype.
 472            (Correlates are correlating phenotypes in different species;
 473            inspired by mouse correlates of human phenotypes in the OMIM
 474            database.)
 475  Returns : A list of Bio::Phenotype::Correlate objects.
 476  Args    :
 477
 478 =cut
 479
 480 sub each_Correlate {
 481     my ( $self ) = @_;
 482
 483     $self->throw_not_implemented();
 484
 485 } # each_Correlate
 486
 487
 488
 489
 490 =head2 add_Correlates
 491
 492  Title   : add_Correlates
 493  Usage   : $obj->add_Correlates( @corrs );
 494            or
 495            $obj->add_Correlates( $corr );
 496  Function: Pushes one or more Bio::Phenotype::Correlate objects
 497            into the list of Correlates.
 498  Returns :
 499  Args    : Bio::Phenotype::Correlate object(s).
 500
 501 =cut
 502
 503 sub add_Correlates {
 504     my ( $self ) = @_;
 505
 506     $self->throw_not_implemented();
 507
 508 } # add_Correlates
 509
 510
 511 =head2 remove_Correlates
 512
 513  Title   : remove_Correlates
 514  Usage   : $obj->remove_Correlates();
 515  Function: Deletes (and returns) the list of Bio::Phenotype::Correlate objects
 516            associated with this phenotype.
 517  Returns : A list of Bio::Phenotype::Correlate objects.
 518  Args    :
 519
 520 =cut
 521
 522 sub remove_Correlates {
 523     my ( $self ) = @_;
 524
 525     $self->throw_not_implemented();
 526
 527 } # remove_Correlates
 528
 529
 530
 531
 532 =head2 each_Measure
 533
 534  Title   : each_Measure()
 535  Usage   : @ms = $obj->each_Measure();
 536  Function: Returns a list of Bio::Phenotype::Measure objects
 537            associated with this phenotype.
 538            (Measure is for biochemically defined phenotypes
 539            or any other types of measures.)
 540  Returns : A list of Bio::Phenotype::Measure objects.
 541  Args    :
 542
 543 =cut
 544
 545 sub each_Measure {
 546     my ( $self ) = @_;
 547
 548     $self->throw_not_implemented();
 549
 550 } # each_Measure
 551
 552
 553 =head2 add_Measures
 554
 555  Title   : add_Measures
 556  Usage   : $obj->add_Measures( @ms );
 557            or
 558            $obj->add_Measures( $m );
 559  Function: Pushes one or more Bio::Phenotype::Measure objects
 560            into the list of Measures.
 561  Returns :
 562  Args    : Bio::Phenotype::Measure object(s).
 563
 564 =cut
 565
 566 sub add_Measures {
 567     my ( $self ) = @_;
 568
 569     $self->throw_not_implemented();
 570
 571 } # add_Measures
 572
 573
 574 =head2 remove_Measures
 575
 576  Title   : remove_Measures
 577  Usage   : $obj->remove_Measures();
 578  Function: Deletes (and returns) the list of Bio::Phenotype::Measure objects
 579            associated with this phenotype.
 580  Returns : A list of Bio::Phenotype::Measure objects.
 581  Args    :
 582
 583 =cut
 584
 585 sub remove_Measures {
 586     my ( $self ) = @_;
 587
 588     $self->throw_not_implemented();
 589
 590 } # remove_Measures
 591
 592
 593
 594
 595 =head2 each_keyword
 596
 597  Title   : each_keyword()
 598  Usage   : @kws = $obj->each_keyword();
 599  Function: Returns a list of key words [scalars, most likely Strings]
 600            associated with this phenotype.
 601  Returns : A list of scalars.
 602  Args    :
 603
 604 =cut
 605
 606 sub each_keyword {
 607     my ( $self ) = @_;
 608
 609     $self->throw_not_implemented();
 610
 611 } # each_keyword
 612
 613
 614 =head2 add_keywords
 615
 616  Title   : add_keywords
 617  Usage   : $obj->add_keywords( @kws );
 618            or
 619            $obj->add_keywords( $kw );
 620  Function: Pushes one or more keywords [scalars, most likely Strings]
 621            into the list of key words.
 622  Returns :
 623  Args    : scalar(s).
 624
 625 =cut
 626
 627 sub add_keywords {
 628     my ( $self ) = @_;
 629
 630     $self->throw_not_implemented();
 631
 632 } # add_keywords
 633
 634
 635 =head2 remove_keywords
 636
 637  Title   : remove_keywords
 638  Usage   : $obj->remove_keywords();
 639  Function: Deletes (and returns) the list of key words [scalars,
 640            most likely Strings] associated with this phenotype.
 641  Returns : A list of scalars.
 642  Args    :
 643
 644 =cut
 645
 646 sub remove_keywords {
 647     my ( $self ) = @_;
 648
 649     $self->throw_not_implemented();
 650
 651 } # remove_keywords
 652
 653
 654
 655
 656 =head2 each_DBLink
 657
 658  Title   : each_DBLink()
 659  Usage   : @dbls = $obj->each_DBLink();
 660  Function: Returns a list of Bio::Annotation::DBLink objects
 661            associated with this phenotype.
 662  Returns : A list of Bio::Annotation::DBLink objects.
 663  Args    :
 664
 665 =cut
 666
 667 sub each_DBLink {
 668     my ( $self ) = @_;
 669
 670     $self->throw_not_implemented();
 671
 672 }
 673
 674
 675 =head2 add_DBLinks
 676
 677  Title   : add_DBLinks
 678  Usage   : $obj->add_DBLinks( @dbls );
 679            or
 680            $obj->add_DBLinks( $dbl );
 681  Function: Pushes one or more Bio::Annotation::DBLink objects
 682            into the list of DBLinks.
 683  Returns :
 684  Args    : Bio::Annotation::DBLink object(s).
 685
 686 =cut
 687
 688 sub add_DBLinks {
 689     my ( $self ) = @_;
 690
 691     $self->throw_not_implemented();
 692
 693 } # add_DBLinks
 694
 695
 696 =head2 remove_DBLinks
 697
 698  Title   : remove_DBLinks
 699  Usage   : $obj->remove_DBLinks();
 700  Function: Deletes (and returns) the list of Bio::Annotation::DBLink objects
 701            associated with this phenotype.
 702  Returns : A list of Bio::Annotation::DBLink objects.
 703  Args    :
 704
 705 =cut
 706
 707 sub remove_DBLinks {
 708     my ( $self ) = @_;
 709
 710     $self->throw_not_implemented();
 711
 712 } # remove_DBLinks
 713
 714
 715
 716
 717 =head2 each_Genotype
 718
 719  Title   : each_Reference()
 720  Usage   : @gts = $obj->each_Reference();
 721  Function: Returns a list of "Genotype" objects
 722            associated with this phenotype.
 723            {* the "genotypes" data member and its methods certainly will/needs to be
 724            changed/improved in one way or another since there is
 725            no "Genotype" class yet, CZ 09/06/02 *}
 726  Returns : A list of "Genotype" objects.
 727  Args    :
 728
 729 =cut
 730
 731 sub each_Genotype {
 732     my ( $self ) = @_;
 733
 734     $self->throw_not_implemented();
 735
 736 } # each_Genotype
 737
 738
 739 =head2 add_Genotypes
 740
 741  Title   : add_Genotypes
 742  Usage   : $obj->add_Genotypes( @gts );
 743            or
 744            $obj->add_Genotypes( $gt );
 745  Function: Pushes one or more "Genotypes"
 746            into the list of "Genotypes".
 747  Returns :
 748  Args    : "Genotypes(s)".
 749
 750 =cut
 751
 752 sub add_Genotypes {
 753     my ( $self ) = @_;
 754
 755     $self->throw_not_implemented();
 756
 757 } # add_Genotypes
 758
 759
 760 =head2 remove_Genotypes
 761
 762  Title   : remove_Genotypes
 763  Usage   : $obj->remove_Genotypes();
 764  Function: Deletes (and returns) the list of "Genotype" objects
 765            associated with this phenotype.
 766  Returns : A list of "Genotype" objects.
 767  Args    :
 768
 769 =cut
 770
 771 sub remove_Genotypes {
 772     my ( $self ) = @_;
 773
 774     $self->throw_not_implemented();
 775
 776 } # remove_Genotypes
 777
 778
 779
 780
 781
 782 1;