Provided by: libbio-perl-perl_1.6.923-1_all bug

NAME

       Bio::SeqIO::chadoxml - chadoxml sequence output stream

SYNOPSIS

       It is probably best not to use this object directly, but rather go through the SeqIO
       handler system:

           $writer = Bio::SeqIO->new(-file => ">chado.xml",
                                     -format => 'chadoxml');

           # assume you already have Sequence or SeqFeature objects
           $writer->write_seq($seq_obj);

           #after writing all seqs
           $writer->close_chadoxml();

DESCRIPTION

       This object can transform Bio::Seq objects to chadoxml flat file databases (for chadoxml
       DTD, see http://gmod.cvs.sourceforge.net/gmod/schema/chado/dat/chado.dtd).

       This is currently a write-only module.

           $seqio = Bio::SeqIO->new(-file => '>outfile.xml',
                                    -format => 'chadoxml'
                                    -suppress_residues => 1,
                                    -allow_residues => 'chromosome',
                                    );

           # we have a Bio::Seq object $seq which is a gene located on
           # chromosome arm 'X', to be written out to chadoxml
           # before converting to chadoxml, $seq object B<must> 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   => 'Homo',
                             -species => 'sapiens',
                             -seq_so_type=>'gene',
                             -src_feature=>'X',
                             -src_feat_type=>'chromosome_arm',
                               -nounflatten=>1,
                             -is_analysis=>'true',
                             -data_source=>'GenBank');

       The chadoxml output of Bio::SeqIO::chadoxml->write_seq() method can be passed to the
       loader utility in XORT package
       (http://gmod.cvs.sourceforge.net/gmod/schema/XMLTools/XORT/) to be loaded into chado.

       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.

       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.

       Destination of data in the subject Bio::Seq object $seq is as following:

           *$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 'symbol' or 'label' tag: feature uniquename, if
                            none of these is present, the chadoxml object
                            generates feature uniquenames as:
                            <gene>-<feature_type>-<span>
                            (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;

       Things to watch out for:

           *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's and
                                    cvterm's 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 'nullpub' of type 'null
                                    pub' needs to be inserted.

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://redmine.open-bio.org/projects/bioperl/

AUTHOR - Peili Zhang

       Email peili@morgan.harvard.edu

APPENDIX

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

   write_seq
        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=>'true' or 'false',
                         -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.

       When $srcfeature (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 $seq object, a featureloc record is
       generated for the top -level feature on $srcfeature. when $srcfeature is given,
       $srcfeattype must also be present. All feature coordinates in $seq should be against
       $srcfeature. $seqSOtype is the optional SO 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 "DNA", when converting to chadoxml, a $seqSOtype argument of
       "golden_path_region" can be supplied to save the scaffold as a feature of type
       "golden_path_region" in chadoxml, instead of "DNA". a feature with primary tag of 'source'
       must be present in the sequence feature list of $seq, to decribe the whole sequence
       record.

       In the current implementation:

       ·  non-mRNA records

          A top-level feature of type $seq->alphabet is generated for the whole GenBank record,
          features listed are unflattened for DNA records to build gene model feature graph, and
          for the other types of records all features in $seq are treated as subfeatures of the
          top-level feature.

       ·  mRNA records

          If a 'gene' feature is present, it must 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 $seq are treated as subfeatures of the mRNA feature.

   suppress_residues
        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)

   allow_residues
        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   :

   return_ftype_hash
        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   :

   return_reltypename
        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   :

   next_seq
        Title    : next_seq
        Usage    : $obj->next_seq
        Function :
        Returns  :
        Args     :
        Status   : Not implemented (write only adaptor)

   _create_writer
        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   :

   close_chadoxml
        Title    : close_chadoxml
        Usage    : $obj->close_chadoxml
        Function : Writes the closing xml tag
        Returns  : None
        Args     : None
        Status   :

   handle_unreserved_tags
        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   :

   handle_Alias_tag
        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   :

   handle_Ontology_tag
        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   :

   handle_dbxref
        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   :

   handle_source
        Title    : handle_source
        Usage    : $obj->handle_source
        Function :
        Returns  :
        Args     :
        Status   :

   _srcf_hash
        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   :