.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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::GeneMap 3pm"
.TH Bio::Map::GeneMap 3pm "2017-01-15" "perl v5.24.1" "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::GeneMap \- A MapI implementation to represent the area around a gene
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    use Bio::Map::GeneMap;
\&    use Bio::Map::Gene;
\&    use Bio::Map::TranscriptionFactor;
\&    use Bio::Map::GeneRelative;
\&
\&        # make some maps that will represent an area around a particular gene in
\&        # particular species (by default, the map represents the area in the genome
\&    # 1000bp upstream of the gene)
\&    my $map1 = Bio::Map::GeneMap\->get(\-gene => \*(AqBRCA2\*(Aq,
\&                                      \-species => \*(Aqhuman\*(Aq,
\&                                      \-description => \*(Aqbreast cancer 2, early onset\*(Aq);
\&        my $map2 = Bio::Map::GeneMap\->get(\-gene => \*(AqBRCA2\*(Aq,
\&                                      \-species => \*(Aqmouse\*(Aq);
\&
\&        # model a TF that binds 500bp upstream of the BRCA2 gene in humans and
\&        # 250bp upstream of BRCA2 in mice
\&        my $rel = Bio::Map::GeneRelative\->new(\-description => "gene start");
\&    my $tf = Bio::Map::TranscriptionFactor\->get(\-universal_name => \*(Aqtf1\*(Aq);
\&        Bio::Map::Position\->new(\-map => $map1,
\&                            \-element => $tf,
\&                            \-start => \-500,
\&                            \-length => 10,
\&                            \-relative => $rel);
\&        Bio::Map::Position\->new(\-map => $map2,
\&                            \-element => $tf,
\&                            \-start => \-250,
\&                            \-length => 10,
\&                            \-relative => $rel);
\&
\&        # find out all the things that map near BRCA2 in all species
\&        foreach my $map ($gene\->known_maps) {
\&                foreach my $thing ($map\->get_elements) {
\&            next if $thing eq $gene;
\&            foreach my $pos ($thing\->get_positions($map)) {
\&                print "In species ", $map\->species, ", ",
\&                      $thing\->universal_name, " maps at ", $pos\->value,
\&                      " relative to ", $pos\->relative\->description, " of gene ",
\&                      $gene\->universal_name, "\en";
\&            }
\&                }
\&        }
\&    
\&    # a GeneMap isa PrimarySeq and so can have sequence associated with it
\&    $map1\->seq(\*(AqATGC\*(Aq);
\&    my $subseq = $map1\->subseq(2,3); # TG
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Model the abstract notion of the area around a gene \- you don't care exactly
where this area is in the genome, you just want to be able to say \*(L"something
binds upstream of gene X\*(R" and \*(L"something else binds 20bp upstream of the first
something\*(R" etc.
.PP
It's useful for modelling transcription factor bindings sites, letting you find
out which transcription factors bind near a gene of interest, or which genes
are bound by a transcription factor of interest.
.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 10
\& Title   : new
\& Usage   : my $obj = Bio::Map::GeneMap\->new();
\& Function: Builds a new Bio::Map::GeneMap object (that has placed on it a
\&           mappable element (Bio::Map::Gene) representing a gene).
\& Returns : Bio::Map::GeneMap
\& Args    : \-gene        => string name of the gene this map will be for
\&                           (in a form common to all species that have the gene,
\&                           but unique amongst non\-orthologous genes) or a
\&                           Bio::Map::Gene object, REQUIRED
\&           \-species     => Bio::Taxon or string representing species, REQUIRED
\&           \-uid         => string, unique identifier for this map (must be
\&                           unique amongst all gene/species combinations)
\&           \-description => string, free text description of the gene
\&           \-upstream    => int, the number of bases the map extends before the
\&                           start of the gene element (default 1000).
\&           \-downstream  => int, the number of bases the map extends beyond the
\&                           end of the gene element (default 0).
\&           \-seq         => string, the sequence of the map, presumably the
\&                           genomic sequence \-upstream bases of the gene,
\&                           including the gene, and \-downstream bases of the gene
.Ve
.SS "get"
.IX Subsection "get"
.Vb 10
\& Title   : get
\& Usage   : my $map = Bio::Map::GeneMap\->get();
\& Function: Builds a new Bio::Map::GeneMap object (like new()), or gets a
\&           pre\-existing one that corresponds to your arguments.
\& Returns : Bio::Map::GeneMap
\& Args    : \-gene        => string name of the gene this map will be for
\&                           (in a form common to all species that have the gene,
\&                           but unique amongst non\-orthologous genes) or a
\&                           Bio::Map::Gene object, REQUIRED
\&           \-species     => Bio::Taxon or string representing species, REQUIRED
\&           \-uid         => string, unique identifier for this map (must be
\&                           unique amongst all gene/species combinations)
\&           \-description => string, free text description of the gene
\&           \-upstream    => int, the number of bases the map extends before the
\&                           start of the gene element (default 1000).
\&           \-downstream  => int, the number of bases the map extends beyond the
\&                           end of the gene element (default 0).
\&           \-seq         => string, the sequence of the map, presumably the
\&                           genomic sequence \-upstream bases of the gene,
\&                           including the gene, and \-downstream bases of the gene
\&
\&           If you supply a \-uid, and a map had previously been created and
\&           given that uid, that same map object will be returned. Otherwise, the
\&           combination of \-gene and \-species will be used to determine
\&           if the same map had previously been made. If a corresponding map
\&           hadn\*(Aqt previously been made, a new map object will be created and
\&           returned.
.Ve
.SS "unique_id"
.IX Subsection "unique_id"
.Vb 5
\& Title   : unique_id
\& Usage   : my $id = $map\->unique_id;
\& Function: Get/set the unique ID for this map
\& Returns : string
\& Args    : none to get, OR string to set
.Ve
.SS "species"
.IX Subsection "species"
.Vb 6
\& Title   : species
\& Usage   : my $species = $map\->species;
\& Function: Get/set Species for a map. It is not recommended to change this once
\&           set.
\& Returns : Bio::Taxon object or string
\& Args    : none to get, OR Bio::Taxon or string to set
.Ve
.SS "type"
.IX Subsection "type"
.Vb 5
\& Title   : type
\& Usage   : my $type = $map\->type
\& Function: Get Map type
\& Returns : string \*(Aqgene\*(Aq
\& Args    : none
.Ve
.SS "gene"
.IX Subsection "gene"
.Vb 10
\& Title   : gene
\& Usage   : my $gene = $map\->gene;
\&           $map\->gene(\-gene => $gene);
\& Function: Get/set the mappable element on this map that represents the gene
\&           this map is for. Once set, it is not recommended to re\-set the gene
\&           to something else. Behaviour in that case is undefined.
\& Returns : Bio::Map::Gene
\& Args    : none to get, OR to set:
\&           \-gene        => Bio::Map::Gene or string of the universal name (see
\&                           Bio::Map::Gene docs), REQUIRED
\&           \-description => string, applied to the Bio::Map::Gene
\&           \-upstream    => int, the number of bases the map extends before the
\&                           start of the gene element (default 1000).
\&           \-downstream  => int, the number of bases the map extends beyond the
\&                           end of the gene element (default 0).
.Ve
.SS "universal_name"
.IX Subsection "universal_name"
.Vb 6
\& Title   : universal_name
\& Usage   : my $name = $map\->universal_name
\& Function: Get/set the name of Bio::Map::Gene object associated with this map.
\&           It is not recommended to change this once set.
\& Returns : string
\& Args    : none to get, OR string to set
.Ve
.SS "upstream"
.IX Subsection "upstream"
.Vb 8
\& Title   : upstream
\& Usage   : my $distance = $map\->upstream;
\&           $map\->upstream($distance);
\& Function: Get/set how long the map is before the start of the Bio::Map::Gene
\&           object on this map.
\& Returns : int
\& Args    : none to get, OR int to set (the number of bases the map extends
\&           before the start of the gene)
.Ve
.SS "downstream"
.IX Subsection "downstream"
.Vb 8
\& Title   : downstream
\& Usage   : my $distance = $map\->downstream;
\&           $map\->downstream($distance);
\& Function: Get/set the nominal end of the map relative to the end of the
\&           Bio::Map::Gene object on this map.
\& Returns : int
\& Args    : none to get, OR int to set (the number of bases the map extends
\&           beyond the end of the gene)
.Ve
.SS "length"
.IX Subsection "length"
.Vb 8
\& Title   : length
\& Usage   : my $length = $map\->length();
\& Function: Retrieves the length of the map. This is normally the length of the
\&           upstream region + length of the gene + length of the downstream
\&           region, but may be longer if positions have been placed on the map
\&           beyond the end of the nominal downstream region.
\& Returns : int
\& Args    : none
.Ve
.SS "seq"
.IX Subsection "seq"
.Vb 12
\& Title   : seq
\& Usage   : $string = $obj\->seq()
\& Function: Get/set the sequence as a string of letters. When getting, If the
\&           GeneMap object didn\*(Aqt have sequence attached directly to it for the
\&           region requested, the map\*(Aqs gene\*(Aqs database will be asked for the
\&           sequence, and failing that, the map\*(Aqs gene\*(Aqs positions will be asked
\&           for their sequences. Areas for which no sequence could be found will
\&           be filled with Ns, unless no sequence was found anywhere, in which
\&           case undef is returned.
\& Returns : string
\& Args    : Optionally on set the new value (a string). An optional second
\&           argument presets the alphabet (otherwise it will be guessed).
.Ve
.SS "subseq"
.IX Subsection "subseq"
.Vb 10
\& Title   : subseq
\& Usage   : $substring = $obj\->subseq(10, 40);
\& Function: Returns the subseq from start to end, where the first base
\&           is 1 and the number is inclusive, ie 1\-2 are the first two
\&           bases of the sequence. If the GeneMap object didn\*(Aqt have sequence
\&           attached directly to it for the region requested, the map\*(Aqs gene\*(Aqs
\&           database will be asked for the sequence, and failing that, the map\*(Aqs
\&           gene\*(Aqs positions will be asked for their sequences. Areas for which
\&           no sequence could be found will be filled with Ns, unless no
\&           sequence was found anywhere, in which case undef is returned. subseq
\&           requests that extend beyond the end of the map will throw.
\& Returns : string
\& Args    : integer for start position AND integer for end position
\&                 OR
\&           Bio::LocationI location for subseq (strand honored)
\&                 OR
\&           Bio::RangeI (eg. a Bio::Map::PositionI)
.Ve