Bio::SeqIO::chadoxml(3)

NAME
Bio::SeqIO::chadoxml - chadoxml sequence input/output stream

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

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

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

DESCRIPTION
This object can transform Bio::Seq objects to and from chadoxml flat file databases (for chadoxml DTD, see http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/gmod/schema/chado/dat/chado.dtd).
 CURRENTLY ONLY TO

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

    # 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,
                      -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://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/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 id's: 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://www.bioperl.org/MailList.shtml  - About the mailing lists

  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:

  http://bugzilla.bioperl.org

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.
           Current implementation:
           1. for 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.
           2. for mRNA records,
           if a 'gene' feature is present, it B<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.
 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.