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

FreeBSD Manual Pages


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

       Bio::PrimarySeq - Bioperl lightweight sequence object

	 # Bio::SeqIO for file reading,	Bio::DB::GenBank for
	 # database reading

	 use Bio::Seq;
	 use Bio::SeqIO;
	 use Bio::DB::GenBank;

	 # make	from memory

	 $seqobj = Bio::PrimarySeq->new	(
	     -seq	       => 'ATGGGGTGGGCGGTGGGTGGTTTG',
	     -id	       => 'GeneFragment-12',
	     -accession_number => 'X78121',
	     -alphabet	       => 'dna',
	     -is_circular      => 1,
	 print "Sequence ", $seqobj->id(), " with accession ",
	   $seqobj->accession_number, "\n";

	 # read	from file

	 $inputstream =	Bio::SeqIO->new(
	     -file   =>	"myseq.fa",
	     -format =>	'Fasta',
	 $seqobj = $inputstream->next_seq();
	 print "Sequence ", $seqobj->id(), " and desc ", $seqobj->desc,	"\n";

	 # to get out parts of the sequence.

	 print "Sequence ", $seqobj->id(), " with accession ",
	   $seqobj->accession_number, "	and desc ", $seqobj->desc, "\n";

	 $string  = $seqobj->seq();
	 $string2 = $seqobj->subseq(1,40);

       PrimarySeq is a lightweight sequence object, storing the	sequence, its
       name, a computer-useful unique name, and	other fundamental attributes.
       It does not contain sequence features or	other information.  To have a
       sequence	with sequence features you should use the Seq object which
       uses this object.

       Although	new users will use Bio::PrimarySeq a lot, in general you will
       be using	it from	the Bio::Seq object. For more information on Bio::Seq
       see Bio::Seq. For interest you might like to know that Bio::Seq has-a
       Bio::PrimarySeq and forwards most of the	function calls to do with
       sequence	to it (the has-a relationship lets us get out of a otherwise
       nasty cyclical reference	in Perl	which would leak memory).

       Sequence	objects	are defined by the Bio::PrimarySeqI interface, and
       this object is a	pure Perl implementation of the	interface. If that's
       gibberish to you, don't worry. The take home message is that this
       object is the bioperl default sequence object, but other	people can use
       their own objects as sequences if they so wish. If you are interested
       in wrapping your	own objects as compliant Bioperl sequence objects,
       then you	should read the	Bio::PrimarySeqI documentation

       The documentation of this object	is a merge of the Bio::PrimarySeq and
       Bio::PrimarySeqI	documentation.	This allows all	the methods which you
       can call	on sequence objects here.

   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.			- General discussion	- About	the mailing lists

       Please direct usage questions or	support	issues to the mailing list:

       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

AUTHOR - Ewan Birney

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

	Title	: new
	Usage	: $seqobj = Bio::PrimarySeq->new( -seq => 'ATGGGGGTGGTGGTACCCT',
						  -id  => 'human_id',
						  -accession_number => 'AL000012',
	Function: Returns a new	primary	seq object from
		  basic	constructors, being a string for the sequence
		  and strings for id and accession_number.

		  Note that you	can provide an empty sequence string. However, in
		  this case you	MUST specify the type of sequence you wish to
		  initialize by	the parameter -alphabet. See alphabet()	for possible
	Returns	: a new	Bio::PrimarySeq	object
	Args	: -seq		    => sequence	string
		  -ref_to_seq	    => ... or reference	to a sequence string
		  -display_id	    => display id of the sequence (locus name)
		  -accession_number => accession number
		  -primary_id	    => primary id (Genbank id)
		  -version	    => version number
		  -namespace	    => the namespace for the accession
		  -authority	    => the authority for the namespace
		  -description	    => description text
		  -desc		    => alias for description
		  -alphabet	    => skip alphabet guess and set it to dna, rna or protein
		  -id		    => alias for display id
		  -is_circular	    => boolean to indicate that	sequence is circular
		  -direct	    => boolean to directly set sequences. The next time	-seq,
				       seq() or	-ref_to_seq is use, the	sequence will not be
				       validated. Be careful with this...
		  -nowarnonempty    => boolean to avoid	warning	when sequence is empty

	Title	: seq
	Usage	: $string = $seqobj->seq();
	Function: Get or set  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 you should not	rely on	this. An error is thrown if
		  the sequence contains	invalid	characters: see	validate_seq().
	Returns	: A scalar
	Args	: - Optional new sequence value	(a string) to set
		  - Optional alphabet (it is guessed by	default)

	Title	: validate_seq
	Usage	: if(! $seqobj->validate_seq($seq_str) ) {
		       print "sequence $seq_str	is not valid for an object of
		       alphabet	",$seqobj->alphabet, "\n";
	Function: Test that the	given sequence is valid, i.e. contains only valid
		  characters. The allowed characters are all letters (A-Z) and '-','.',
		  '*','?','=' and '~'. Spaces are not valid. Note that this
		  implementation does not take alphabet() into account and that	empty
		  sequences are	considered valid.
	Returns	: 1 if the supplied sequence string is valid, 0	otherwise.
	Args	: - Sequence string to be validated
		  - Boolean to optionally throw	an error if the	sequence is invalid

	Title	: subseq
	Usage	: $substring = $seqobj->subseq(10,40);
		  $substring = $seqobj->subseq(10,40,'nogap');
		  $substring = $seqobj->subseq(-start=>10, -end=>40, -replace_with=>'tga');
		  $substring = $seqobj->subseq($location_obj);
		  $substring = $seqobj->subseq($location_obj, -nogap =>	1);
	Function: Return the subseq from start to end, where the first sequence
		  character has	coordinate 1 number is inclusive, ie 1-2 are the
		  first	two characters of the sequence.	The given start	coordinate
		  has to be larger than	the end, even if the sequence is circular.
	Returns	: a string
	Args	: integer for start position
		  integer for end position
		  Bio::LocationI location for subseq (strand honored)
		  Specify -NOGAP=>1 to return subseq with gap characters removed
		  Specify -REPLACE_WITH=>$new_subseq to	replace	the subseq returned
		  with $new_subseq in the sequence object

	Title	: length
	Usage	: $len = $seqobj->length();
	Function: Get the stored length	of the sequence	in number of symbols (bases
		  or amino acids). In some circumstances, you can also set this	attribute:

		  1. For empty sequences, you can set the length to anything you want:
		     my	$seqobj	= Bio::PrimarySeq->new(	-length	=> 123 );
		     my	$len = $seqobj->len; # 123
		  2. To	save memory when using very long sequences, you	can set	the
		     length of the sequence to the length of the sequence (and nothing
		     my	$seqobj	= Bio::PrimarySeq->new(	-seq =>	'ACGT...' ); # 1 Mbp sequence
		     # process $seqobj... then after you're done with it
		     $seqobj->seq(undef); # free memory!
		     my	$len = $seqobj->len; # 1 Mbp

		  Note that if you set seq() to	a value	other than undef at any	time,
		  the length attribute will be reset.
	Returns	: integer representing the length of the sequence.
	Args	: Optionally, the value	on set

	Title	: display_id or	display_name
	Usage	: $id_string = $seqobj->display_id();
	Function: Get or set the display id, aka 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.

		  With the new Bio::DescribeableI interface, display_name aliases
		  to this method.
	Returns	: A string for the display ID
	Args	: Optional string for the display ID to	set

	Title	: accession_number or object_id
	Usage	: $unique_key =	$seqobj->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".

		  [Note	this method name is likely to change in	1.3]

		  With the new Bio::IdentifiableI interface, this is aliased
		  to object_id
	Returns	: A string
	Args	: A string (optional) for setting

	Title	: primary_id
	Usage	: $unique_key =	$seqobj->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	natural	primary	id, this method
		  should return	a stringified memory location.
	Returns	: A string
	Args	: A string (optional, for setting)

	Title	: alphabet
	Usage	: if( $seqobj->alphabet	eq 'dna' ) { # Do something }
	Function: Get/set the alphabet of sequence, 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 type - if there is	no alphabet specified it
		  has to guess.
	Args	: optional string to set : 'dna' | 'rna' | 'protein'

	Title	: desc or description
	Usage	: $seqobj->desc($newval);
	Function: Get/set description of the sequence.

		  'description'	is an alias for	this for compliance with the
		  Bio::DescribeableI interface.
	Returns	: value	of desc	(a string)
	Args	: newvalue (a string or	undef, optional)

	Title	: can_call_new
	Usage	:
	Example	:
	Returns	: true
	Args	:

	Title	: id
	Usage	: $id =	$seqobj->id();
	Function: This is mapped on display_id
	Example	:
	Returns	:
	Args	:

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

Methods	for Bio::IdentifiableI compliance
	Title	: object_id
	Usage	: $string = $seqobj->object_id();
	Function: Get or set a string which represents the stable primary identifier
		  in this namespace of this object. For	DNA sequences this
		  is its accession_number, similarly for protein sequences.

		  This is aliased to accession_number().
	Returns	: A scalar
	Args	: Optional object ID to	set.

	Title	: version
	Usage	: $version = $seqobj->version();
	Function: Get or set a number which differentiates between versions of
		  the same object. Higher numbers are considered to be
		  later	and more relevant, but a single	object described
		  the same identifier should represent the same	concept.
	Returns	: A number
	Args	: Optional version to set.

	Title	: authority
	Usage	: $authority = $seqobj->authority();
	Function: Get or set a string which represents the organisation	which
		  granted the namespace, written as the	DNS name of the
		  organisation (eg,
	Returns	: A scalar
	Args	: Optional authority to	set.

	Title	: namespace
	Usage	: $string = $seqobj->namespace();
	Function: Get or set a string representing the name space this identifier
		  is valid in, often the database name or the name describing the
	Returns	: A scalar
	Args	: Optional namespace to	set.

Methods	for Bio::DescribableI compliance
       This comprises of display_name and description.

	Title	: display_name
	Usage	: $string = $seqobj->display_name();
	Function: Get or set a string which is what should be displayed	to the user.
		  The string should have no spaces (ideally, though a cautious
		  user of this interface would not assumme this) and should be
		  less than thirty characters (though again, double checking
		  this is a good idea).

		  This is aliased to display_id().
	Returns	: A string for the display name
	Args	: Optional string for the display name to set.

	Title	: description
	Usage	: $string = $seqobj->description();
	Function: Get or set a text string suitable for	displaying to the user a
		  description. This string is likely to	have spaces, but
		  should not have any newlines or formatting - just plain
		  text.	The string should not be greater than 255 characters
		  and clients can feel justified at truncating strings at 255
		  characters for the purposes of display.

		  This is aliased to desc().
	Returns	: A string for the description
	Args	: Optional string for the description to set.

Methods	Inherited from Bio::PrimarySeqI
       These methods are available on Bio::PrimarySeq, although	they are
       actually	implemented on Bio::PrimarySeqI

	Title	: revcom
	Usage	: $rev = $seqobj->revcom();
	Function: Produces a new Bio::SeqI 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 orginal 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:

		  $seqobj = $seqobj->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::SeqI object
	Args	: none

	Title	: trunc
	Usage	: $subseq = $myseq->trunc(10,100);
	Function: Provides a truncation	of a sequence,
	Returns	: A fresh Bio::SeqI implementing object.
	Args	: Numbers for the start	and end	positions

Internal methods
       These are internal methods to PrimarySeq

	Title	: _guess_alphabet
	Usage	:
	Function: Automatically	guess and set the type of sequence: dna, rna, protein
		  or ''	if the sequence	was empty. This	method first removes dots (.),
		  dashes (-) and question marks	(?) before guessing the	alphabet
		  using	the IUPAC conventions for ambiguous residues. Since the	DNA and
		  RNA characters are also valid	characters for proteins, there is
		  no foolproof way of determining the right alphabet. This is our best
		  guess	only!
	Returns	: string 'dna',	'rna', 'protein' or ''.
	Args	: none

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

NAME | SYNOPSIS | DESCRIPTION | FEEDBACK | AUTHOR - Ewan Birney | APPENDIX | Methods for Bio::IdentifiableI compliance | Methods for Bio::DescribableI compliance | Methods Inherited from Bio::PrimarySeqI | Internal methods

Want to link to this manual page? Use this URL:

home | help