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

FreeBSD Manual Pages

  
 
  

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

NAME
       Bio::SeqIO::bsml	- BSML sequence	input/output stream

SYNOPSIS
       It is probably best not to use this object directly, but	rather go
       through the SeqIO handler system. To read a BSML	file:

	   $stream = Bio::SeqIO->new( -file => $filename, -format => 'bsml');

	   while ( my $bioSeqObj = $stream->next_seq() ) {
	       # do something with $bioSeqObj
	   }

       To write	a Seq object to	the current file handle	in BSML	XML format:

	   $stream->write_seq( -seq => $seqObj);

       If instead you would like a XML::DOM object containing the BSML,	use:

	   my $newXmlObject = $stream->to_bsml(	-seq =>	$seqObj);

DESCRIPTION
       This object can transform Bio::Seq objects to and from BSML (XML)
       flatfiles.

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

   Things Still	to Do
       o   The module now uses the new Collection.pm system. However,
	   Annotations associated with a Feature object	still seem to use the
	   old system, so parsing with the old methods are included..

       o   Generate Seq	objects	with no	sequence data but an assigned length.
	   This	appears	to be an issue with Bio::Seq. It is possible (and
	   reasonable) to make a BSML document with features but no sequence
	   data.

       o   Support "Seq-data-import". Do not know how commonly this is used.

       o   Some	features are awaiting implementation in	later versions of
	   BSML. These include:

	   o   Nested feature support

	   o   Complex feature (ie joins)

	   o   Unambiguity in strand (ie -1,0,1, not just  'complement'	)

	   o   More friendly dblink structures

       o   Location.pm (or RangeI::union?) appears to have a bug when 'expand'
	   is used.

       o   More	intelligent hunting for	sequence and feature titles? It	is not
	   terribly clear where	the most appropriate field is located, better
	   grepping (eg	looking	for a reasonable count for spaces and numbers)
	   may allow for titles	better than "AE008041".

AUTHOR - Charles Tilford
       Bristol-Myers Squibb Bioinformatics

       Email tilfordc@bms.com

       I have developed	the BSML specific code for this	package, but have used
       code from other SeqIO packages for much of the nuts-and-bolts. In
       particular I have used code from	the embl.pm module either directly or
       as a framework for many of the subroutines that are common to SeqIO
       modules.

METHODS
   next_seq
	Title	: next_seq
	Usage	: my $bioSeqObj	= $stream->next_seq
	Function: Retrieves the	next sequence from a SeqIO::bsml stream.
	Returns	: A reference to a Bio::Seq::RichSeq object
	Args	:

   to_bsml
	Title	: to_bsml
	Usage	: my $domDoc = $obj->to_bsml(@args)
	Function: Generates an XML structure for one or	more Bio::Seq objects.
		  If $seqref is	an array ref, the XML tree generated will include
		  all the sequences in the array.
	Returns	: A reference to the XML DOM::Document object generated	/ modified
	Args	: Argument array in form of -key => val. Recognized keys:

	     -seq A Bio::Seq reference,	or an array reference of many of them

	  -xmldoc Specifies an existing	XML DOM	document to add	the sequences
		  to. If included, then	only data (no page formatting) will
		  be added. If not, a new XML::DOM::Document will be made,
		  and will be populated	with both <Sequence> data, as well as
		  <Page> display elements.

	  -nodisp Do not generate <Display> elements, or any children
		  thereof, even	if -xmldoc is not set.

	-skipfeat If set to 'all', all <Feature>s will be skipped.  If it is
		  a hash reference, any	<Feature> with a class matching	a key
		  in the hash will be skipped -	for example, to	skip 'source'
		  and 'score' features,	use:

		      -skipfeat	=> { source => 'Y', score => 'Y' }

	-skiptags As above: if set to 'all', no	tags are included, and if a
		  hash reference, those	specific tags will be ignored.

		  Skipping some	or all tags and	features can result in
		  noticeable speed improvements.

	  -nodata If true, then	<Seq-data> will	not be included.  This may be
		  useful if you	just want annotations and do not care about
		  the raw ACTG information.

	  -return Default is 'xml', which will return a	reference to the BSML
		  XML object. If set to	'seq' will return an array ref of the
		  <Sequence> objects added (rather than	the whole XML object)

	   -close Early	BSML browsers will crash if an element *could* have
		  children but does not, and is	closed as an empty element
		  e.g. <Styles/>. If -close is true, then such tags are	given
		  a comment child to explicitly	close them e.g.	 <Styles><!--
		  --></Styles>.	This is	default	true, set to "0" if you	do
		  not want this	behavior.

	Examples : my $domObj =	$stream->to_bsml( -seq => \@fourCoolSequenceObjects,
						  -skipfeat => { source	=> 1 },
						 );

		   # Or	add sequences to an existing BSML document:
		   $stream->to_bsml(-seq => \@fourCoolSequenceObjects,
				    -skipfeat => { source => 1 },
				    -xmldoc => $myBsmlDocumentInProgress,  );

   write_seq
	Title	: write_seq
	Usage	: $obj->write_seq(@args)
	Function: Prints out an	XML structure for one or more Bio::Seq objects.
		  If $seqref is	an array ref, the XML tree generated will include
		  all the sequences in the array. This method is fairly	simple,
		  most of the processing is performed within to_bsml.
	Returns	: A reference to the XML object	generated / modified
	Args	: Argument array. Recognized keys:

	     -seq A Bio::Seq reference,	or an array reference of many of them

		  Alternatively, the method may	be called simply as...

		  $obj->write_seq( $bioseq )

		  ... if only a	single argument	is passed, it is assumed that
		  it is	the sequence object (can also be an array ref of
		  many Seq objects )

	     -printmime	If true	prints "Content-type: $mimetype\n\n" at	top of
		  document, where $mimetype is the value designated by this
		  key. For generic XML use text/xml, for BSML use text/x-bsml

	     -return This option will be suppressed, since the nature of this
		  method is to print out the XML document. If you wish to
		  retrieve the <Sequence> objects generated, use the to_bsml
		  method directly.

INTERNAL METHODS
       The following methods are used for internal processing, and should
       probably	not be accessed	by the user.

   _parse_location
	Title	: _parse_location
	Usage	: $obj->_parse_location($xmlDocument, $parentElem, $SeqFeatureObj)
	Function: Adds <Interval-loc> and <Site-loc> children to <$parentElem> based
		  on locations / sublocations found in $SeqFeatureObj. If
		  sublocations exist, the original location will be ignored.
	Returns	: An array ref containing the elements added to	the parent.
		  These	will have already been added to	<$parentElem>
	Args	: 0 The	DOM::Document being modified
		  1 The	DOM::Element parent that you want to add to
		  2 Reference to the Bio::SeqFeature being analyzed

   _parse_bsml_feature
	Title	: _parse_bsml_feature
	Usage	: $obj->_parse_bsml_feature($xmlFeature	)
	Function: Will examine the <Feature> element provided by $xmlFeature and
		  return a generic seq feature.
	Returns	: Bio::SeqFeature::Generic
	Args	: 0 XML::DOM::Element <Feature>	being analyzed.

   _parse_bsml_location
	Title	: _parse_bsml_location
	Usage	: $obj->_parse_bsml_feature( $intOrSiteLoc, $gsfObject )
	Function: Will examine the <Interval-loc> or <Site-loc>	element	provided
	Returns	: Bio::SeqFeature::Generic
	Args	: 0 XML::DOM::Element <Interval/Site-loc> being	analyzed.
		  1 Optional SeqFeature::Generic to use

   _parse_reference
	Title	: _parse_reference
	Usage	: $obj->_parse_reference(@args )
	Function: Makes	a new <Reference> object from a	::Reference, which is
		  then stored in an array provide by -refs. It will be
		  appended to the XML tree later.
	Returns	:
	Args	: Argument array. Recognized keys:

	     -xml The DOM::Document being modified

	     -refobj The Annotation::Reference Object

	     -refs An array reference to hold the new <Reference> DOM object

	     -id Optional. If the XML id for the 'calling' element is
		  provided, it will be placed in any <Reference> refs
		  attribute.

   _parse_annotation
	Title	: _parse_annotation
	Usage	: $obj->_parse_annotation(@args	)
	Function: Will examine any Annotations found in	-obj. Data found in
		  ::Comment and	::DBLink structures, as	well as	Annotation
		  description fields are stored	in -desc for later
		  generation of	<Attribute>s. <Reference> objects are generated
		  from ::References, and are stored in -refs - these will
		  be appended to the XML tree later.
	Returns	:
	Args	: Argument array. Recognized keys:

	     -xml The DOM::Document being modified

	     -obj Reference to the Bio object being analyzed

	     -descr An array reference for holding description text items

	     -refs An array reference to hold <Reference> DOM objects

	     -id Optional. If the XML id for the 'calling' element is
		  provided, it will be placed in any <Reference> refs
		  attribute.

   _parse_annotation_old
	   Title   : _parse_annotation_old
	Usage	: $obj->_parse_annotation_old(@args)
	Function: As above, but	for the	old Annotation system.
		  Apparently needed because Features are still using the old-style
		  annotations?
	Returns	:
	Args	: Argument array. Recognized keys:

	     -xml The DOM::Document being modified

	     -obj Reference to the Bio object being analyzed

	     -descr An array reference for holding description text items

	     -refs An array reference to hold <Reference> DOM objects

	     -id Optional. If the XML id for the 'calling' element is
		  provided, it will be placed in any <Reference> refs
		  attribute.

   _add_page
	Title	: _add_page
	Usage	: $obj->_add_page($xmlDocument,	$xmlSequenceObject)
	Function: Adds a simple	<Page> and <View> structure for	a <Sequence>
	Returns	: a reference to the newly created <Page>
	Args	: 0 The	DOM::Document being modified
		  1 Reference to the <Sequence>	object

   _addel
	Title	: _addel
	Usage	: $obj->_addel($parentElem, 'ChildName',
			       { anAttr	=> 'someValue',	anotherAttr => 'aValue',})
	Function: Add an element with attribute	values to a DOM	tree
	Returns	: a reference to the newly added element
	Args	: 0 The	DOM::Element parent that you want to add to
		  1 The	name of	the new	child element
		  2 Optional hash reference containing
		    attribute name => attribute	value assignments

   _show_dna
	Title	: _show_dna
	Usage	: $obj->_show_dna($newval)
	Function: (cut-and-pasted directly from	embl.pm)
	Returns	: value	of _show_dna
	Args	: newvalue (optional)

   _initialize
	Title	: _initialize
	Usage	: $dom = $obj->_initialize(@args)
	Function: Coppied from embl.pm,	and augmented with initialization of the
		  XML DOM tree
	Returns	:
	Args	: -file	=> the XML file	to be parsed

   _parseparams
	Title	: _parseparams
	Usage	: my $paramHash	= $obj->_parseparams(@args)
	Function: Borrowed from	Bio::Parse.pm, who borrowed it from CGI.pm
		  Lincoln Stein	-> Richard Resnick -> here
	Returns	: A hash reference of the parameter keys (uppercase) pointing to
		  their	values.
	Args	: An array of key, value pairs.	Easiest	to pass	values as:
		  -key1	=> value1, -key2 => value2, etc
		  Leading "-" are removed.

   _parse_xml
	Title	: _parse_xml
	Usage	: $dom = $obj->_parse_xml($filename)
	Function: uses XML::DOM	to construct a DOM tree	from the BSML document
	Returns	: a reference to the parsed DOM	tree
	Args	: 0 Path to the	XML file needing to be parsed

TESTING	SCRIPT
       The following script may	be used	to test	the conversion process.	You
       will need a file	of the format you wish to test.	The script will
       convert the file	to BSML, store it in /tmp/bsmltemp, read that file
       into a new SeqIO	stream,	and write it back as the original format.
       Comparison of this second file to the original input file will allow
       you to track where data may be lost or corrupted. Note that you will
       need to specify $readfile and $readformat.

	use Bio::SeqIO;
	# Tests	preservation of	details	during round-trip conversion:
	# $readformat -> BSML -> $readformat
	my $tempspot = "/tmp/bsmltemp";	 # temp	folder to hold generated files
	my $readfile = "rps4y.embl";	 # The name of the file	you want to test
	my $readformat = "embl";	 # The format of the file being	tested

	system "mkdir $tempspot" unless	(-d $tempspot);
	# Make Seq object from the $readfile
	my $biostream =	Bio::SeqIO->new( -file => "$readfile" );
	my $seq	= $biostream->next_seq();

	# Write	BSML from SeqObject
	my $bsmlout = Bio::SeqIO->new(-format => 'bsml',
				      -file => ">$tempspot/out.bsml");
	warn "\nBSML written to	$tempspot/out.bsml\n";
	$bsmlout->write_seq($seq);
	# Need to kill object for following code to work... Why	is this	so?
	$bsmlout = "";

	# Make Seq object from BSML
	my $bsmlin = Bio::SeqIO->new(-file => "$tempspot/out.bsml",
				     -format =>	'bsml');
	my $seq2 = $bsmlin->next_seq();

	# Write	format back from Seq Object
	my $genout = Bio::SeqIO->new(-format =>	$readformat,
				     -file => ">$tempspot/out.$readformat");
	$genout->write_seq($seq2);
	warn "$readformat  written to $tempspot/out.$readformat\n";

	# BEING	LOST:
	# Join information (not	possible in BSML 2.2)
	# Sequence type	(??)

perl v5.32.1			  2019-12-07		   Bio::SeqIO::bsml(3)

NAME | SYNOPSIS | DESCRIPTION | FEEDBACK | AUTHOR - Charles Tilford | METHODS | INTERNAL METHODS | TESTING SCRIPT

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

home | help