Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Bio::PrimarySeqI(3)   User Contributed Perl Documentation  Bio::PrimarySeqI(3)

NAME
       Bio::PrimarySeqI	- Interface definition for a Bio::PrimarySeq

SYNOPSIS
	   # Bio::PrimarySeqI is the interface class for sequences.
	   # If	you are	a newcomer to bioperl, you might want to start with
	   # Bio::Seq documentation.

	   # Test if this is a seq object
	   $obj->isa("Bio::PrimarySeqI") ||
	     $obj->throw("$obj does not	implement the Bio::PrimarySeqI interface");

	   # Accessors
	   $string    =	$obj->seq();
	   $substring =	$obj->subseq(12,50);
	   $display   =	$obj->display_id();	  # for	human display
	   $id	      =	$obj->primary_id();	  # unique id for this object,
						  # implementation defined
	   $unique_key=	$obj->accession_number(); # unique biological id

	   # Object manipulation
	   eval	{
	      $rev = $obj->revcom();
	   };
	   if( $@ ) {
	      $obj->throw( "Could not reverse complement. ".
			   "Probably not DNA. Actual exception\n$@\n" );
	   }

	   $trunc = $obj->trunc(12,50);
	   # $rev and $trunc are Bio::PrimarySeqI compliant objects

DESCRIPTION
       This object defines an abstract interface to basic sequence information
       - for most users	of the package the documentation (and methods) in this
       class are not useful - this is a	developers-only	class which defines
       what methods have to be implmented by other Perl	objects	to comply to
       the Bio::PrimarySeqI interface. Go "perldoc Bio::Seq" or	"man Bio::Seq"
       for more	information on the main	class for sequences.

       PrimarySeq is an	object just for	the sequence and its name(s), nothing
       more. Seq is the	larger object complete with features. There is a pure
       perl implementation of this in Bio::PrimarySeq. If you just want	to use
       Bio::PrimarySeq objects,	then please read that module first. This
       module defines the interface, and is of more interest to	people who
       want to wrap their own Perl Objects/RDBs/FileSystems etc	in way that
       they "are" bioperl sequence objects, even though	it is not using	Perl
       to store	the sequence etc.

       This interface defines what bioperl considers necessary to "be" a
       sequence, without providing an implementation of	this, an
       implementation is provided in Bio::PrimarySeq. If you want to provide a
       Bio::PrimarySeq-compliant object	which in fact wraps another
       object/database/out-of-perl experience, then this is the	correct	thing
       to wrap,	generally by providing a wrapper class which would inherit
       from your object	and this Bio::PrimarySeqI interface. The wrapper class
       then would have methods lists in	the "Implementation Specific
       Functions" which	would provide these methods for	your object.

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 one
       of the Bioperl mailing lists.  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
       the bugs	and their resolution.  Bug reports can be submitted via	the
       web:

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

AUTHOR - Ewan Birney
       Email birney@ebi.ac.uk

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

Implementation-specific	Functions
       These functions are the ones that a specific implementation must
       define.

   seq
	Title	: seq
	Usage	: $string = $obj->seq()
	Function: Returns the sequence as a string of letters. The
		  case of the letters is left up to the	implementer.
		  Suggested cases are upper case for proteins and lower	case for
		  DNA sequence (IUPAC standard), but implementations are suggested to
		  keep an open mind about case (some users... want mixed case!)
	Returns	: A scalar
	Status	: Virtual

   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, i.e. 1-2 are the first two
		  bases	of the sequence.

		  Start	cannot be larger than end but can be equal.

	Returns	: A string
	Args	:
	Status	: Virtual

   display_id
	Title	: display_id
	Usage	: $id_string = $obj->display_id();
	Function: Returns the display id, also known as	the common name	of the Sequence
		  object.

		  The semantics	of this	is that	it is the most likely string
		  to be	used as	an identifier of the sequence, and likely to
		  have "human" readability.  The id is equivalent to the ID
		  field	of the GenBank/EMBL databanks and the id field of the
		  Swissprot/sptrembl database. In fasta	format,	the >(\S+) is
		  presumed to be the id, though	some people overload the id
		  to embed other information. Bioperl does not use any
		  embedded information in the ID field,	and people are
		  encouraged to	use other mechanisms (accession	field for
		  example, or extending	the sequence object) to	solve this.

		  Notice that $seq->id() maps to this function,	mainly for
		  legacy/convenience reasons.
	Returns	: A string
	Args	: None
	Status	: Virtual

   accession_number
	Title	: accession_number
	Usage	: $unique_biological_key = $obj->accession_number;
	Function: Returns the unique biological	id for a sequence, commonly
		  called the accession_number. For sequences from established
		  databases, the implementors should try to use	the correct
		  accession number. Notice that	primary_id() provides the
		  unique id for	the implemetation, allowing multiple objects
		  to have the same accession number in a particular implementation.

		  For sequences	with no	accession number, this method should return
		  "unknown".
	Returns	: A string
	Args	: None
	Status	: Virtual

   primary_id
	Title	: primary_id
	Usage	: $unique_implementation_key = $obj->primary_id;
	Function: Returns the unique id	for this object	in this
		  implementation. This allows implementations to manage	their
		  own object ids in a way the implementaiton can control
		  clients can expect one id to map to one object.

		  For sequences	with no	accession number, this method should
		  return a stringified memory location.

	Returns	: A string
	Args	: None
	Status	: Virtual

   can_call_new
	Title	: can_call_new
	Usage	: if( $obj->can_call_new ) {
		    $newobj = $obj->new( %param	);
		}
	Function: Can_call_new returns 1 or 0 depending
		  on whether an	implementation allows new
		  constructor to be called. If a new constructor
		  is allowed, then it should take the followed hashed
		  constructor list.

		  $myobject->new( -seq => $sequence_as_string,
				  -display_id  => $id
				  -accession_number => $accession
				  -alphabet => 'dna',
				  );
	Returns	: 1 or 0
	Args	:

   alphabet
	Title	: alphabet
	Usage	: if( $obj->alphabet eq	'dna' )	{ /Do Something/ }
	Function: Returns the type of sequence being one of
		  'dna', 'rna' or 'protein'. This is case sensitive.

		  This is not called "type" because this would cause
		  upgrade problems from	the 0.5	and earlier Seq	objects.

	Returns	: A string either 'dna','rna','protein'. NB - the object must
		  make a call of the alphabet, if there	is no alphabet specified it
		  has to guess.
	Args	: None
	Status	: Virtual

   moltype
	Title	: moltype
	Usage	: Deprecated. Use alphabet() instead.

Implementation-optional	Functions
       The following functions rely on the above functions. An implementing
       class does not need to provide these functions, as they will be
       provided	by this	class, but is free to override these functions.

       The revcom(), trunc(), and translate() methods create new sequence
       objects.	They will call new() on	the class of the sequence object
       instance	passed as argument, unless can_call_new() returns FALSE. In
       the latter case a Bio::PrimarySeq object	will be	created. Implementors
       which really want to control how	objects	are created (eg, for object
       persistence over	a database, or objects in a CORBA framework), they are
       encouraged to override these methods

   revcom
	Title	: revcom
	Usage	: $rev = $seq->revcom()
	Function: Produces a new Bio::PrimarySeqI implementing object which
		  is the reversed complement of	the sequence. For protein
		  sequences this throws	an exception of	"Sequence is a
		  protein. Cannot revcom".

		  The id is the	same id	as the original	sequence, and the
		  accession number is also indentical. If someone wants	to
		  track	that this sequence has be reversed, it needs to
		  define its own extensions.

		  To do	an inplace edit	of an object you can go:

		  $seq = $seq->revcom();

		  This of course, causes Perl to handle	the garbage
		  collection of	the old	object,	but it is roughly speaking as
		  efficient as an inplace edit.

	Returns	: A new	(fresh)	Bio::PrimarySeqI object
	Args	: None

   trunc
	Title	: trunc
	Usage	: $subseq = $myseq->trunc(10,100);
	Function: Provides a truncation	of a sequence.
	Returns	: A fresh Bio::PrimarySeqI implementing	object.
	Args	: Two integers denoting	first and last base of the sub-sequence.

   translate
	Title	: translate
	Usage	: $protein_seq_obj = $dna_seq_obj->translate

		  Or if	you expect a complete coding sequence (CDS) translation,
		  with initiator at the	beginning and terminator at the	end:

		  $protein_seq_obj = $cds_seq_obj->translate(-complete => 1);

		  Or if	you want translate() to	find the first initiation
		  codon	and return the corresponding protein:

		  $protein_seq_obj = $cds_seq_obj->translate(-orf => 1);

	Function: Provides the translation of the DNA sequence using full
		  IUPAC	ambiguities in DNA/RNA and amino acid codes.

		  The complete CDS translation is identical to EMBL/TREMBL
		  database translation.	Note that the trailing terminator
		  character is removed before returning	the translated protein
		  object.

		  Note:	if you set $dna_seq_obj->verbose(1) you	will get a
		  warning if the first codon is	not a valid initiator.

	Returns	: A Bio::PrimarySeqI implementing object
	Args	: -terminator
		      character	for terminator,	default	'*'
		  -unknown
		      character	for unknown, default 'X'
		  -frame
		      positive integer frame shift (in bases), default 0
		  -codontable_id
		      integer codon table id, default 1
		  -complete
		      boolean, if true,	complete CDS is	expected. default false
		  -complete_codons
		      boolean, if true,	codons which are incomplete are	translated if a
		      suitable amino acid is found. For	instance, if the incomplete
		      codon is 'GG', the completed codon is 'GGN', which is glycine
		      (G). Defaults to 'false';	setting	'-complete' also makes this
		      true.
		  -throw
		      boolean, throw exception if ORF not complete, default false
		  -orf
		      if 'longest', find longest ORF.  other true value, find
		      first ORF.  default 0
		  -codontable
		      optional L<Bio::Tools::CodonTable> object	to use for
		      translation
		  -start
		      optional three-character string to force as initiation
		      codon (e.g. 'atg'). If unset, start codons are
		      determined by the	CodonTable.  Case insensitive.
		  -offset
		      optional positive	integer	offset for fuzzy locations.
		      if set, must be either 1,	2, or 3

       Notes

       The -start argument only	applies	when -orf is set to 1. By default all
       initiation codons found in the given codon table	are used but when
       "start" is set to some codon this codon will be used exclusively	as the
       initiation codon. Note that the default codon table (NCBI "Standard")
       has 3 initiation	codons!

       By default translate() translates termination codons to the some
       character (default is *), both internal and trailing codons. Setting
       "-complete" to 1	tells translate() to remove the	trailing character.

       -offset is used for seqfeatures which contain the the \codon_start tag
       and can be set to 1, 2, or 3.  This is the offset by which the sequence
       translation starts relative to the first	base of	the feature

       For details on codon tables used	by translate() see
       Bio::Tools::CodonTable.

       Deprecated argument set (v. 1.5.1 and prior versions) where each
       argument	is an element in an array:

	 1: character for terminator (optional), defaults to '*'.
	 2: character for unknown amino	acid (optional), defaults to 'X'.
	 3: frame (optional), valid values are 0, 1, 2,	defaults to 0.
	 4: codon table	id (optional), defaults	to 1.
	 5: complete coding sequence expected, defaults	to 0 (false).
	 6: boolean, throw exception if	not complete coding sequence
	    (true), defaults to	warning	(false)
	 7: codontable,	a custom Bio::Tools::CodonTable	object (optional).

   transcribe()
	Title	: transcribe
	Usage	: $xseq	= $seq->transcribe
	Function: Convert base T to base U
	Returns	: PrimarySeqI object of	alphabet 'rna' or
		  undef	if $seq->alphabet ne 'dna'
	Args	:

   rev_transcribe()
	Title	: rev_transcribe
	Usage	: $rtseq = $seq->rev_transcribe
	Function: Convert base U to base T
	Returns	: PrimarySeqI object of	alphabet 'dna' or
		  undef	if $seq->alphabet ne 'rna'
	Args	:

   id
	Title	: id
	Usage	: $id =	$seq->id()
	Function: ID of	the sequence. This should normally be (and actually is in
		  the implementation provided here) just a synonym for display_id().
	Returns	: A string.
	Args	:

   length
	Title	: length
	Usage	: $len = $seq->length()
	Function:
	Returns	: Integer representing the length of the sequence.
	Args	:

   desc
	Title	: desc
	Usage	: $seq->desc($newval);
		  $description = $seq->desc();
	Function: Get/set description text for a seq object
	Returns	: Value	of desc
	Args	: newvalue (optional)

   is_circular
	Title	: is_circular
	Usage	: if( $obj->is_circular) { # Do	something }
	Function: Returns true if the molecule is circular
	Returns	: Boolean value
	Args	: none

Private	functions
       These are some private functions	for the	PrimarySeqI interface. You do
       not need	to implement these functions

   _find_orfs_nucleotide
	Title	: _find_orfs_nucleotide
	Usage	:
	Function: Finds	ORF starting at	1st initiation codon in	nucleotide sequence.
		  The ORF is not required to have a termination	codon.
	Example	:
	Returns	: a list of string coordinates of ORF locations	(0-based half-open),
		  sorted descending by length (so that the longest is first)
		  as: [	start, end, frame, length ], [ start, end, frame, length ], ...
	Args	: Nucleotide sequence,
		  CodonTable object,
		  (optional) alternative initiation codon (e.g.	'ATA'),
		  (optional) boolean that, if true, stops after	finding	the
			     first available ORF

   _attempt_to_load_Seq
	Title	: _attempt_to_load_Seq
	Usage	:
	Function:
	Example	:
	Returns	:
	Args	:

perl v5.24.1			  2017-07-08		   Bio::PrimarySeqI(3)

NAME | SYNOPSIS | DESCRIPTION | FEEDBACK | AUTHOR - Ewan Birney | APPENDIX | Implementation-specific Functions | Implementation-optional Functions | Private functions

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Bio::PrimarySeqI&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help