Bio::Map::GeneMap(3pm)					User Contributed Perl Documentation				    Bio::Map::GeneMap(3pm)

NAME

       Bio::Map::GeneMap - A MapI implementation to represent the area around a gene

SYNOPSIS

	   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 => 'BRCA2',
					     -species => 'human',
					     -description => 'breast cancer 2, early onset');
	       my $map2 = Bio::Map::GeneMap->get(-gene => 'BRCA2',
					     -species => 'mouse');

	       # 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 => 'tf1');
	       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, "
";
		   }
		       }
	       }

	   # a GeneMap isa PrimarySeq and so can have sequence associated with it
	   $map1->seq('ATGC');
	   my $subseq = $map1->subseq(2,3); # TG

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 "something binds upstream of gene X" and "something else binds 20bp upstream of the first something" etc.

       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.

       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://redmine.open-bio.org/projects/bioperl/

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 $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

   get
	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't previously been made, a new map object will be created and
		  returned.

   unique_id
	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

   species
	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

   type
	Title	: type
	Usage	: my $type = $map->type
	Function: Get Map type
	Returns : string 'gene'
	Args	: none

   gene
	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).

   universal_name
	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

   upstream
	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)

   downstream
	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)

   length
	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

   seq
	Title	: seq
	Usage	: $string = $obj->seq()
	Function: Get/set the sequence as a string of letters. When getting, If the
		  GeneMap object didn't have sequence attached directly to it for the
		  region requested, the map's gene's database will be asked for the
		  sequence, and failing that, the map's gene's 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).

   subseq
	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't have sequence
		  attached directly to it for the region requested, the map's gene's
		  database will be asked for the sequence, and failing that, the map's
		  gene's 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)

perl v5.14.2							    2012-03-02						    Bio::Map::GeneMap(3pm)