.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Bio::SeqIO::chadoxml 3pm" .TH Bio::SeqIO::chadoxml 3pm "2018-10-27" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Bio::SeqIO::chadoxml \- chadoxml sequence output stream .SH "SYNOPSIS" .IX Header "SYNOPSIS" It is probably best not to use this object directly, but rather go through the SeqIO handler system: .PP .Vb 2 \& $writer = Bio::SeqIO\->new(\-file => ">chado.xml", \& \-format => \*(Aqchadoxml\*(Aq); \& \& # assume you already have Sequence or SeqFeature objects \& $writer\->write_seq($seq_obj); \& \& #after writing all seqs \& $writer\->close_chadoxml(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This object can transform Bio::Seq objects to chadoxml flat file databases (for chadoxml \s-1DTD,\s0 see http://gmod.cvs.sourceforge.net/gmod/schema/chado/dat/chado.dtd). .PP This is currently a write-only module. .PP .Vb 5 \& $seqio = Bio::SeqIO\->new(\-file => \*(Aq>outfile.xml\*(Aq, \& \-format => \*(Aqchadoxml\*(Aq \& \-suppress_residues => 1, \& \-allow_residues => \*(Aqchromosome\*(Aq, \& ); \& \& # we have a Bio::Seq object $seq which is a gene located on \& # chromosome arm \*(AqX\*(Aq, to be written out to chadoxml \& # before converting to chadoxml, $seq object B be transformed \& # so that all the coordinates in $seq are against the source \& # feature to be passed into Bio::SeqIO::chadoxml\->write_seq() \& # \-\- chromosome arm X in the example below. \& \& $seqio\->write_seq(\-seq=>$seq, \& \-genus => \*(AqHomo\*(Aq, \& \-species => \*(Aqsapiens\*(Aq, \& \-seq_so_type=>\*(Aqgene\*(Aq, \& \-src_feature=>\*(AqX\*(Aq, \& \-src_feat_type=>\*(Aqchromosome_arm\*(Aq, \& \-nounflatten=>1, \& \-is_analysis=>\*(Aqtrue\*(Aq, \& \-data_source=>\*(AqGenBank\*(Aq); .Ve .PP The chadoxml output of Bio::SeqIO::chadoxml\->\fIwrite_seq()\fR method can be passed to the loader utility in \s-1XORT\s0 package (http://gmod.cvs.sourceforge.net/gmod/schema/XMLTools/XORT/) to be loaded into chado. .PP This object is currently implemented to work with sequence and annotation data from whole genome projects deposited in GenBank. It may not be able to handle all different types of data from all different sources. .PP In converting a Bio::Seq object into chadoxml, a top-level feature is created to represent the object and all sequence features inside the Bio::Seq object are treated as subfeatures of the top-level feature. The Bio::SeqIO::chadoxml object calls Bio::SeqFeature::Tools::Unflattener to unflatten the flat feature list contained in the subject Bio::Seq object, to build gene model containment hierarchy conforming to chado central dogma model: gene \&\-\-> mRNA \-\-> exons and protein. .PP Destination of data in the subject Bio::Seq object \f(CW$seq\fR is as following: .PP .Vb 1 \& *$seq\->display_id: name of the top\-level feature; \& \& *$seq\->accession_number: if defined, uniquename and \& feature_dbxref of the top\-level \& feature if not defined, \& $seq\->display_id is used as the \& uniquename of the top\-level feature; \& \& *$seq\->molecule: transformed to SO type, used as the feature \& type of the top\-level feature if \-seq_so_type \& argument is supplied, use the supplied SO type \& as the feature type of the top\-level feature; \& \& *$seq\->species: organism of the top\-level feature; \& \& *$seq\->seq: residues of the top\-level feature; \& \& *$seq\->is_circular, $seq\->division: feature_cvterm; \& \& *$seq\->keywords, $seq\->desc, comments: featureprop; \& \& *references: pub and feature_pub; \& medline/pubmed ids: pub_dbxref; \& comments: pubprop; \& \& *feature "source" span: featureloc for top\-level feature; \& \& *feature "source" db_xref: feature_dbxref for top\-level feature; \& \& *feature "source" other tags: featureprop for top\-level feature; \& \& *subfeature \*(Aqsymbol\*(Aq or \*(Aqlabel\*(Aq tag: feature uniquename, if \& none of these is present, the chadoxml object \& generates feature uniquenames as: \& \-\- \& (e.g. foo\-mRNA\-\-1000..3000); \& \& *gene model: feature_relationship built based on the \& containment hierarchy; \& \& *feature span: featureloc; \& \& *feature accession numbers: feature_dbxref; \& \& *feature tags (except db_xref, symbol and gene): featureprop; .Ve .PP Things to watch out for: .PP .Vb 2 \& *chado schema change: this version works with the chado \& version tagged chado_1_01 in GMOD CVS. \& \& *feature uniquenames: especially important if using XORT \& loader to do incremental load into \& chado. may need pre\-processing of the \& source data to put the correct \& uniquenames in place. \& \& *pub uniquenames: chadoxml\->write_seq() has the FlyBase policy \& on pub uniquenames hard\-coded, it assigns \& pub uniquenames in the following way: for \& journals and books, use ISBN number; for \& published papers, use MEDLINE ID; for \& everything else, use FlyBase unique \& identifier FBrf#. need to modify the code to \& implement your policy. look for the comments \& in the code. \& \& *for pubs possibly existing in chado but with no knowledge of \& its uniquename:put "op" as "match", then need to run the \& output chadoxml through a special filter that \& talks to chado database and tries to find the \& pub by matching with the provided information \& instead of looking up by the unique key. after \& matching, the filter also resets the "match" \& operation to either "force" (default), or \& "lookup", or "insert", or "update". the \& "match" operation is for a special FlyBase use \& case. please modify to work according to your \& rules. \& \& *chado initialization for loading: \& \& cv & cvterm: in the output chadoxml, all cv\*(Aqs and \& cvterm\*(Aqs are lookup only. Therefore, \& before using XORT loader to load the \& output into chado, chado must be \& pre\-loaded with all necessary CVs and \& CVterms, including "SO" , "property \& type", "relationship type", "pub type", \& "pubprop type", "pub relationship type", \& "sequence topology", "GenBank feature \& qualifier", "GenBank division". A pub by \& the uniquename \*(Aqnullpub\*(Aq of type \*(Aqnull \& pub\*(Aq needs to be inserted. .Ve .SH "FEEDBACK" .IX Header "FEEDBACK" .SS "Mailing Lists" .IX Subsection "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. .PP .Vb 2 \& bioperl\-l@bioperl.org \- General discussion \& http://bioperl.org/wiki/Mailing_lists \- About the mailing lists .Ve .SS "Support" .IX Subsection "Support" Please direct usage questions or support issues to the mailing list: .PP \&\fIbioperl\-l@bioperl.org\fR .PP 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. .SS "Reporting Bugs" .IX Subsection "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: .PP .Vb 1 \& https://github.com/bioperl/bioperl\-live/issues .Ve .SH "AUTHOR \- Peili Zhang" .IX Header "AUTHOR - Peili Zhang" Email peili@morgan.harvard.edu .SH "APPENDIX" .IX Header "APPENDIX" The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _ .SS "write_seq" .IX Subsection "write_seq" .Vb 11 \& Title : write_seq \& Usage : $stream\->write_seq(\-seq=>$seq, \-seq_so_type=>$seqSOtype, \& \-src_feature=>$srcfeature, \& \-src_feat_type=>$srcfeattype, \& \-nounflatten=>0 or 1, \& \-is_analysis=>\*(Aqtrue\*(Aq or \*(Aqfalse\*(Aq, \& \-data_source=>$datasource) \& Function: writes the $seq object (must be seq) into chadoxml. \& Returns : 1 for success and 0 for error \& Args : A Bio::Seq object $seq, optional $seqSOtype, $srcfeature, \& $srcfeattype, $nounflatten, $is_analysis and $data_source. .Ve .PP When \f(CW$srcfeature\fR (a string, the uniquename of the source feature) is given, the location and strand information of the top-level feature against the source feature will be derived from the sequence feature called 'source' of the \f(CW$seq\fR object, a featureloc record is generated for the top \-level feature on \&\f(CW$srcfeature\fR. when \f(CW$srcfeature\fR is given, \f(CW$srcfeattype\fR must also be present. All feature coordinates in \f(CW$seq\fR should be against \f(CW$srcfeature\fR. \f(CW$seqSOtype\fR is the optional \s-1SO\s0 term to use as the type of the top-level feature. For example, a GenBank data file for a Drosophila melanogaster genome scaffold has the molecule type of \*(L"\s-1DNA\*(R",\s0 when converting to chadoxml, a \f(CW$seqSOtype\fR argument of \&\*(L"golden_path_region\*(R" can be supplied to save the scaffold as a feature of type \&\*(L"golden_path_region\*(R" in chadoxml, instead of \*(L"\s-1DNA\*(R".\s0 a feature with primary tag of 'source' must be present in the sequence feature list of \f(CW$seq\fR, to describe the whole sequence record. .PP In the current implementation: .IP "\(bu" 3 non-mRNA records .Sp A top-level feature of type \f(CW$seq\fR\->alphabet is generated for the whole GenBank record, features listed are unflattened for \s-1DNA\s0 records to build gene model feature graph, and for the other types of records all features in \f(CW$seq\fR are treated as subfeatures of the top-level feature. .IP "\(bu" 3 mRNA records .Sp If a 'gene' feature is present, it \fBmust\fR have a /symbol or /label tag to contain the uniquename of the gene. a top-level feature of type 'gene' is generated. the mRNA is written as a subfeature of the top-level gene feature, and the other sequence features listed in \f(CW$seq\fR are treated as subfeatures of the mRNA feature. .SS "suppress_residues" .IX Subsection "suppress_residues" .Vb 8 \& Title : suppress_residues \& Usage : $obj\->suppress_residues() #get existing value \& $obj\->suppress_residues($newval) #set new value \& Function : Keep track of the flag to suppress printing of residues in the \& chadoxml file. The default it to allow all residues to go into the \& file. \& Returns : value of suppress_residues (a scalar) \& Args : new value of suppress_residues (to set) .Ve .SS "allow_residues" .IX Subsection "allow_residues" .Vb 10 \& Title : allow_residues \& Usage : $obj\->allow_residues() #get existing value \& $obj\->allow_residues($feature_type) #set new value \& Function : Track the allow_residues type. This can be used in conjunction \& with the suppress_residues flag to only allow residues from a \& specific feature type to be printed in the xml file, for example, \& only printing chromosome residues. When suppress_residues is set to \& true, then only chromosome features would would go into the xml \& file. If suppress_residues is not set, this function has no effect \& (since the default is to put all residues in the xml file). \& Returns : value of allow_residues (string that corresponds to a feature type) \& Args : new value of allow_residues (to set) \& Status : .Ve .SS "return_ftype_hash" .IX Subsection "return_ftype_hash" .Vb 8 \& Title : return_ftype_hash \& Usage : $obj\->return_ftype_hash() \& Function : A simple hash where returning it has be factored out of the main \& code to allow subclasses to override it. \& Returns : A hash that indicates what the name of the SO term is and what \& the name of the Sequence Ontology is in the cv table. \& Args : The string that represents the SO term. \& Status : .Ve .SS "return_reltypename" .IX Subsection "return_reltypename" .Vb 7 \& Title : return_reltypename \& Usage : $obj\->return_reltypename \& Function : Return the appropriate relationship type name depending on the \& feature type (typically part_of, but derives_from for polypeptide). \& Returns : A relationship type name. \& Args : A SO type name. \& Status : .Ve .SS "next_seq" .IX Subsection "next_seq" .Vb 6 \& Title : next_seq \& Usage : $obj\->next_seq \& Function : \& Returns : \& Args : \& Status : Not implemented (write only adaptor) .Ve .SS "_create_writer" .IX Subsection "_create_writer" .Vb 6 \& Title : _create_writer \& Usage : $obj\->_create_writer \& Function : Creates XML::Writer object and writes start tag \& Returns : Nothing, though the writer persists as part of the chadoxml object \& Args : None \& Status : .Ve .SS "close_chadoxml" .IX Subsection "close_chadoxml" .Vb 6 \& Title : close_chadoxml \& Usage : $obj\->close_chadoxml \& Function : Writes the closing xml tag \& Returns : None \& Args : None \& Status : .Ve .SS "handle_unreserved_tags" .IX Subsection "handle_unreserved_tags" .Vb 6 \& Title : handle_unreserved_tags \& Usage : $obj\->handle_unreserved_tags \& Function : Converts tag value pairs to xml\-ready hashrefs \& Returns : The array containing the hashrefs \& Args : In order: the Seq or SeqFeature object, the key, and the hasharray \& Status : .Ve .SS "handle_Alias_tag" .IX Subsection "handle_Alias_tag" .Vb 6 \& Title : handle_Alias_tag \& Usage : $obj\->handle_Alias_tag \& Function : Convert Alias values to synonym hash refs \& Returns : An array of synonym hash tags \& Args : The seq or seqFeature object and the synonym hash array \& Status : .Ve .SS "handle_Ontology_tag" .IX Subsection "handle_Ontology_tag" .Vb 6 \& Title : handle_Ontology_tag \& Usage : $obj\->handle_Ontology_tag \& Function : Convert Ontology_term values to ontology term hash refs \& Returns : An array of ontology term hash refs \& Args : The seq or seqFeature object and the ontology term array \& Status : .Ve .SS "handle_dbxref" .IX Subsection "handle_dbxref" .Vb 6 \& Title : handle_dbxref \& Usage : $obj\->handle_dbxref \& Function : Convert Dbxref values to dbxref hashref \& Returns : An array of dbxref hashrefs \& Args : A seq or seqFeature object and the dbxref array \& Status : .Ve .SS "handle_source" .IX Subsection "handle_source" .Vb 6 \& Title : handle_source \& Usage : $obj\->handle_source \& Function : \& Returns : \& Args : \& Status : .Ve .SS "_srcf_hash" .IX Subsection "_srcf_hash" .Vb 7 \& Title : _srcf_hash \& Usage : $obj\->_srcf_hash \& Function : Creates the srcfeature hash for use in featureloc hashes \& Returns : The srcfeature hash \& Args : The srcfeature name, the srcfeature type and a reference to the \& organism hash. \& Status : .Ve