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

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

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