.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::Map::Gene 3pm"
.TH Bio::Map::Gene 3pm "2018-10-27" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Map::Gene \- An gene modelled as a mappable element.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Bio::Map::Gene;
\&
\&  my $gene = Bio::Map::Gene\->get(\-universal_name => \*(AqBRCA2\*(Aq,
\&                                 \-description => \*(Aqbreast cancer 2, early onset\*(Aq);
\&
\&  # 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 => \*(AqBRCA2\*(Aq, \-species => $human);
\&  my $map2 = Bio::Map::GeneMap\->get(\-universal_name => \*(AqBRCA2\*(Aq, \-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 => \*(Aqtranscript\*(Aq);
\&  $gene\->add_transcript_position($trans);
\&  my $exon = Bio::Map::GenePosition\->new(\-start => 0, \-length => 100,
\&                                         \-map => $map1, \-type => \*(Aqexon\*(Aq);
\&  $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\*(Aqve defined the first of many exons which starts at the
\&  #  start of the transcript and is 100bp long)
.Ve
.SH "DESCRIPTION"
.IX Header "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 \*(L"what binds near this gene?\*(R", or \*(L"which genes does this bind near?\*(R".
.PP
See t/Map/Map.t for more example usage.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "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.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Sendu Bala"
.IX Header "AUTHOR - Sendu Bala"
Email bix@sendu.me.uk
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "new"
.IX Subsection "new"
.Vb 8
\& 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
.Ve
.SS "get"
.IX Subsection "get"
.Vb 9
\& 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
.Ve
.SS "universal_name"
.IX Subsection "universal_name"
.Vb 7
\& 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
.Ve
.SS "description"
.IX Subsection "description"
.Vb 10
\& Title   : description
\& Usage   : my $description = $gene\->description();
\&           $gene\->description($description);
\& Function: Get/set information relating to the gene, in this case the
\&           description (eg. \*(Aqfull name of gene\*(Aq)
\& 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
.Ve
.SS "display_id"
.IX Subsection "display_id"
.Vb 10
\& 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. \*(AqENSG00000155287\*(Aq)
\& 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
.Ve
.SS "display_xref"
.IX Subsection "display_xref"
.Vb 10
\& 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. \*(AqHUGO:23472\*(Aq).
\& 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
.Ve
.SS "external_db"
.IX Subsection "external_db"
.Vb 10
\& 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. \*(AqHUGO\*(Aq).
\& 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
.Ve
.SS "external_name"
.IX Subsection "external_name"
.Vb 11
\& 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.
\&           \*(Aqgene_name\*(Aq, 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
.Ve
.SS "biotype"
.IX Subsection "biotype"
.Vb 10
\& Title   : biotype
\& Usage   : my $biotype = $gene\->biotype();
\&           $gene\->biotype($biotype);
\& Function: Get/set information relating to the gene, in this case the biotype
\&           (eg. \*(Aqprotein_coding\*(Aq).
\& 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
.Ve
.SS "source"
.IX Subsection "source"
.Vb 10
\& Title   : source
\& Usage   : my $source = $gene\->source();
\&           $gene\->source($source);
\& Function: Get/set information relating to the gene, in this case the source
\&           (eg. \*(Aq??\*(Aq).
\& 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
.Ve
.SS "position"
.IX Subsection "position"
.Vb 10
\& 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 \*(Aqmain\*(Aq 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.
.Ve
.SS "add_transcript_position"
.IX Subsection "add_transcript_position"
.Vb 12
\& 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 \*(Aqgene\*(Aq mappable on
\&           this transcript\*(Aqs map. The first position added using this method
\&           must have a start of 0. The supplied Position will be given a type of
\&           \*(Aqtranscript\*(Aq and relative of (gene => 0). The active_transcript for
\&           the Position\*(Aqs 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)
.Ve
.SS "active_transcript"
.IX Subsection "active_transcript"
.Vb 10
\& 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 \*(Aqthe\*(Aq 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
.Ve
.SS "get_transcript_positions"
.IX Subsection "get_transcript_positions"
.Vb 6
\& 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
.Ve
.SS "get_transcript_position"
.IX Subsection "get_transcript_position"
.Vb 9
\& Title   : get_transcript_position
\& Usage   : my $position = $gene\->get_transcript_position($map, $int);
\& Function: Get the $int\*(Aqth 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)
.Ve
.SS "coding_position"
.IX Subsection "coding_position"
.Vb 5
\& 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 \*(Aqcoding\*(Aq 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
.Ve
.SS "add_exon_position"
.IX Subsection "add_exon_position"
.Vb 11
\& 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 \*(Aqexon\*(Aq 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)
.Ve
.SS "get_exon_positions"
.IX Subsection "get_exon_positions"
.Vb 8
\& 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\*(Aqth
\&           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)
.Ve
.SS "get_exon_position"
.IX Subsection "get_exon_position"
.Vb 10
\& Title   : get_exon_position
\& Usage   : my $position = $gene\->get_exon_position($map, $exon_num, $int);
\& Function: Get the $exon_num\*(Aqth exon position that is relative to the $int\*(Aqth
\&           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)
.Ve
.SS "add_intron_position"
.IX Subsection "add_intron_position"
.Vb 11
\& 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 \*(Aqintron\*(Aq
\&           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)
.Ve
.SS "get_intron_positions"
.IX Subsection "get_intron_positions"
.Vb 8
\& 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\*(Aqth
\&           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)
.Ve
.SS "get_intron_position"
.IX Subsection "get_intron_position"
.Vb 9
\& Title   : get_intron_position
\& Usage   : my $position = $gene\->get_intron_position($map, $intron_num, $int);
\& Function: Get the $intron_num\*(Aqth intron position that is relative to the
\&           $int\*(Aqth 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)
.Ve
.SS "set_from_db"
.IX Subsection "set_from_db"
.Vb 10
\& 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
.Ve