Provided by: libbio-perl-perl_1.6.924-3_all bug

NAME

       Bio::Map::Gene - An gene modelled as a mappable element.

SYNOPSIS

         use Bio::Map::Gene;

         my $gene = Bio::Map::Gene->get(-universal_name => 'BRCA2',
                                        -description => 'breast cancer 2, early onset');

         # Normally you get Gene objects from GeneMaps
         use Bio::Map::GeneMap;

         # Model a gene with its orthologous versions found in different species,
         # but at abstract locations within each genome
         my $map1 = Bio::Map::GeneMap->get(-universal_name => 'BRCA2', -species => $human);
         my $map2 = Bio::Map::GeneMap->get(-universal_name => 'BRCA2', -species => $mouse);

         $gene = $map1->gene;

         # Genes can have special kinds of positions (Bio::Map::GenePosition) that
         # define where various sub-regions of the gene are, relative to one of the
         # normal Positions the gene has placing it on a map.
         my $trans = Bio::Map::GenePosition->new(-start => 0, -length => 700,
                                                 -map => $map1, -type => 'transcript');
         $gene->add_transcript_position($trans);
         my $exon = Bio::Map::GenePosition->new(-start => 0, -length => 100,
                                                -map => $map1, -type => 'exon');
         $gene->add_exon_position($exon, 1);
         # (so now the gene has 1 transcript 700bp long which starts at the beginning
         #  of the gene, and we've defined the first of many exons which starts at the
         #  start of the transcript and is 100bp long)

DESCRIPTION

       Model a gene as an abstract mappable element. This is for when you don't care exactly
       where a gene is in a genome, but just want to model other things (like transcription
       factor binding sites) that are near it so you can answer questions like "what binds near
       this gene?", or "which genes does this bind near?".

       See t/Map/Map.t for more example usage.

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to the Bioperl mailing list.  Your participation
       is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their
       resolution. Bug reports can be submitted via the web:

         https://github.com/bioperl/bioperl-live/issues

AUTHOR - Sendu Bala

       Email bix@sendu.me.uk

APPENDIX

       The rest of the documentation details each of the object methods.  Internal methods are
       usually preceded with a _

   new
        Title   : new
        Usage   : my $gene = Bio::Map::Gene->new();
        Function: Builds a new Bio::Map::Gene object
        Returns : Bio::Map::Gene
        Args    : -universal_name => string : name of the gene (in a form common to all
                                              species that have the gene, but unique
                                              amongst non-orthologous genes), REQUIRED
                  -description => string    : free text description of the gene

   get
        Title   : get
        Usage   : my $gene = Bio::Map::Gene->get();
        Function: Builds a new Bio::Map::Gene object (like new()), or gets a
                  pre-existing one that shares the same universal_name.
        Returns : Bio::Map::Gene
        Args    : -universal_name => string, name of the gene (in a form common to all
                                     species that have the gene, but unique amongst
                                     non-orthologous genes), REQUIRED
                  -description    => string, free text description of the gene

   universal_name
        Title   : universal_name
        Usage   : my $name = $gene->universal_name
        Function: Get/Set Mappable name, corresponding to the name of the gene in a
                  form shared by orthologous versions of the gene in different species,
                  but otherwise unique.
        Returns : string
        Args    : none to get, OR string to set

   description
        Title   : description
        Usage   : my $description = $gene->description();
                  $gene->description($description);
        Function: Get/set information relating to the gene, in this case the
                  description (eg. 'full name of gene')
        Returns : string (empty string if not defined)
        Args    : none to get general version, OR Bio::Map::GeneMap to get map-specific
                  version.
                  string to set general version, optionally AND Bio::Map::GeneMap to
                  set map-specific version

   display_id
        Title   : display_id
        Usage   : my $display_id = $gene->display_id();
                  $gene->display_id($display_id);
        Function: Get/set information relating to the gene, in this case the
                  display_id (eg. 'ENSG00000155287')
        Returns : string (empty string if not defined)
        Args    : none to get general version, OR Bio::Map::GeneMap to get map-specific
                  version.
                  string to set general version, optionally AND Bio::Map::GeneMap to
                  set map-specific version

   display_xref
        Title   : display_xref
        Usage   : my $display_xref = $gene->display_xref();
                  $gene->display_xref($display_xref);
        Function: Get/set information relating to the gene, in this case the
                  display_xref (eg. 'HUGO:23472').
        Returns : string (empty string if not defined)
        Args    : none to get general version, OR Bio::Map::GeneMap to get map-specific
                  version.
                  string to set general version, optionally AND Bio::Map::GeneMap to
                  set map-specific version

   external_db
        Title   : external_db
        Usage   : my $external_db = $gene->external_db();
                  $gene->external_db($external_db);
        Function: Get/set information relating to the gene, in this case the
                  external_db (eg. 'HUGO').
        Returns : string (empty string if not defined)
        Args    : none to get general version, OR Bio::Map::GeneMap to get map-specific
                  version.
                  string to set general version, optionally AND Bio::Map::GeneMap to
                  set map-specific version

   external_name
        Title   : external_name
        Usage   : my $external_name = $gene->external_name();
                  $gene->external_name($external_name);
        Function: Get/set information relating to the gene, in this case the (eg.
                  'gene_name', probably the same as or similar to what you set
                  universal_name() to, but could be a species-specific alternative).
        Returns : string (empty string if not defined)
        Args    : none to get general version, OR Bio::Map::GeneMap to get map-specific
                  version.
                  string to set general version, optionally AND Bio::Map::GeneMap to
                  set map-specific version

   biotype
        Title   : biotype
        Usage   : my $biotype = $gene->biotype();
                  $gene->biotype($biotype);
        Function: Get/set information relating to the gene, in this case the biotype
                  (eg. 'protein_coding').
        Returns : string (empty string if not defined)
        Args    : none to get general version, OR Bio::Map::GeneMap to get map-specific
                  version.
                  string to set general version, optionally AND Bio::Map::GeneMap to
                  set map-specific version

   source
        Title   : source
        Usage   : my $source = $gene->source();
                  $gene->source($source);
        Function: Get/set information relating to the gene, in this case the source
                  (eg. '??').
        Returns : string (empty string if not defined)
        Args    : none to get general version, OR Bio::Map::GeneMap to get map-specific
                  version.
                  string to set general version, optionally AND Bio::Map::GeneMap to
                  set map-specific version

   position
        Title   : position
        Usage   : my $position = $mappable->position($map);
        Function: Get the main Position of this Mappable on a given map. (A gene may
                  have many positions on a map, but all but one of them are
                  Bio::Map::GenePosition objects that describe sub-regions of the gene
                  which are relative to the 'main' Bio::Map::Position position, which
                  is the only one that is directly relative to the map - this is the
                  Position returned by this method.)
        Returns : Bio::Map::Position
        Args    : L<Bio::Map::MapI> object.

   add_transcript_position
        Title   : add_transcript_position
        Usage   : $gene->add_transcript_position($position);
        Function: Set the bounds of a transcript on a map (that of the supplied
                  position). All transcript positions added this way must have
                  coordinates relative to the main position of the 'gene' mappable on
                  this transcript's map. The first position added using this method
                  must have a start of 0. The supplied Position will be given a type of
                  'transcript' and relative of (gene => 0). The active_transcript for
                  the Position's map will be set to this one.
        Returns : n/a
        Args    : Bio::Map::GenePosition (which must have its map() defined, and be for
                  a map this gene is on)

   active_transcript
        Title   : active_transcript
        Usage   : my $active = $gene->active_transcript($map);
                  $gene->active_transcript($map, $int);
        Function: Get/set the active transcript number (an int of 1 would mean the 1st
                  transcript position added to the object for the given map, ie. would
                  correspond to the the 1st Position object in the list returned by
                  get_transcript_positions($map)). The active transcript is the one
                  considered by other methods and objects when dealing with positions
                  relative to 'the' transcript.
        Returns : int, 0 means there were no transcript positions on the given map,
                  undef is some other problem
        Args    : Just Bio::Map::GeneMap to get
                  Bio::Map::GeneMap AND int to set

   get_transcript_positions
        Title   : get_transcript_positions
        Usage   : my @transcript_positions = $gene->get_transcript_positions($map);
        Function: Get all the transcript positions of this gene on the given map, in
                  the order they were added to the map.
        Returns : list of Bio::Map::GenePosition
        Args    : Bio::Map::GeneMap

   get_transcript_position
        Title   : get_transcript_position
        Usage   : my $position = $gene->get_transcript_position($map, $int);
        Function: Get the $int'th transcript position added to the map. If no
                  transcripts have been added to the map, and the default transcript
                  was requested, $gene->position is returned, as that will have the
                  same start and end as the first transcript.
        Returns : Bio::Map::GenePosition
        Args    : Bio::Map::GeneMap AND int (if int not supplied, or 0, returns
                  the currently active transcript position)

   coding_position
        Title   : coding_position
        Usage   : $gene->coding_position($position, $transcript_number);
                  $gene->coding_position($map, $transcript_number);
        Function: Get/set the bounds of a coding region of a given transcript on a map
                  (that of the supplied position).

                  When setting, coordinates must be relative to the transcript start.
                  The supplied position will be given a type 'coding' and a relative
                  (-transcript => $transcript_number). There can be only one coding
                  position per transcript (hence this is a get/set).

                  When getting, if a coding region has not been defined for the
                  requested transcript, $gene->get_transcript_position($map,
                  $transcript_number) is returned, as if assuming the entirety of the
                  transcript is coding.

        Returns : Bio::Map::GenePosition
        Args    : Bio::Map::GeneMap AND int (the transcript number) to get, OR to set:
                  Bio::Map::GenePosition (which must have its map() defined, and be for
                  a map this gene is on) AND int (the transcript number)
                  In both cases, if transcript number not supplied or 0 this will be
                  resolved to the current active transcript number - there must be at
                  least one transcript on the map

   add_exon_position
        Title   : add_exon_position
        Usage   : $gene->add_exon_position($position, $transcript_number);
        Function: Set the bounds of an exon of a given transcript on a map (that of the
                  supplied position). Coordinates must be relative to the transcript
                  start. The supplied position will be given a type 'exon' and a
                  relative (-transcript => $transcript_number).
        Returns : n/a
        Args    : Bio::Map::GenePosition (which must have its map() defined, and be for
                  a map this gene is on) AND int (the transcript number; if not
                  supplied or 0 this will be resolved to the current active transcript
                  number - there must be at least one transcript on the map)

   get_exon_positions
        Title   : get_exon_positions
        Usage   : my @positions = $gene->get_exon_positions($map, $int);
        Function: Get all the exon positions that are relative to the $int'th
                  transcript position added to the map. Exons are returned sorted by
                  their start positions.
        Returns : array of Bio::Map::GenePosition
        Args    : Bio::Map::GeneMap AND int (the transcript number; if second int not
                  supplied, or 0, considers the currently active transcript)

   get_exon_position
        Title   : get_exon_position
        Usage   : my $position = $gene->get_exon_position($map, $exon_num, $int);
        Function: Get the $exon_num'th exon position that is relative to the $int'th
                  transcript position added to the map. Exons are numbered in Position
                  order, not the order they were added to the map. If no exons have
                  been added to the map, and the first exon was requested,
                  $gene->get_transcript_position($map, $int) is returned, as that will
                  have the same start as the first exon, and could have the same end
                  for a single exon gene.
        Returns : Bio::Map::GenePosition
        Args    : Bio::Map::GeneMap AND int (the exon you want) AND int (the transcript
                  number; if second int not supplied, or 0, considers the currently
                  active transcript)

   add_intron_position
        Title   : add_intron_position
        Usage   : $gene->add_intron_position($position, $transcript_number);
        Function: Set the bounds of an intron of a given transcript on a map (that of
                  the supplied position). Coordinates must be relative to the
                  transcript start. The supplied position will be given a type 'intron'
                  and a relative (-transcript => $transcript_number).
        Returns : n/a
        Args    : Bio::Map::GenePosition (which must have its map() defined, and be for
                  a map this gene is on) AND int (the transcript number; if not
                  supplied or 0 this will be resolved to the current active transcript
                  number - there must be at least one transcript on the map)

   get_intron_positions
        Title   : get_intron_positions
        Usage   : my @positions = $gene->get_intron_positions($map, $int);
        Function: Get all the intron positions that are relative to the $int'th
                  transcript position added to the map. Introns are returned sorted by
                  their start positions.
        Returns : array of Bio::Map::GenePosition
        Args    : Bio::Map::GeneMap AND int (the transcript number; if second int not
                  supplied, or 0, considers the currently active transcript)

   get_intron_position
        Title   : get_intron_position
        Usage   : my $position = $gene->get_intron_position($map, $intron_num, $int);
        Function: Get the $intron_num'th intron position that is relative to the
                  $int'th transcript position added to the map. Introns are numbered in
                  Position order, not the order they were added to the map.
        Returns : Bio::Map::GenePosition
        Args    : Bio::Map::GeneMap AND int (the intron you want) AND int (the
                  transcript number; if second int not supplied, or 0, considers the
                  currently active transcript)

   set_from_db
        Title   : set_from_db
        Usage   : $gene->set_from_db(); # for an instance only
                  Bio::Map::Gene->set_from_db(); # decide that all future genes added
                                                 # to maps will be set from db
        Function: Creates all the various types of positions (transcripts, coding,
                  exons, introns) for this gene on all its maps. The information comes
                  from an Ensembl database via Bio::Tools::Run::Ensembl. NB: will
                  purge any existing Bio::Map::GenePosition objects that were
                  previously on the maps this gene is one.
        Returns : undef on failure, otherwise the number of maps that successfully
                  had positions added to them
        Args    : boolean (no argument/undef is treated as 1, ie. do set from db;
                  supply 0 to turn off)

                  NB: Bio::Tools::Run::Ensembl is available in the bioperl-run package;
                  see it for details on setting up a database to use.

                  Once set, any new maps (species) this gene is added to will
                  automatically also have their positions set_from_db