Florent Angly > Bio-Community > Bio::Community::IO

Download:
Bio-Community-0.001007.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Source  

NAME ^

Bio::Community::IO - Read and write files that describe communities

SYNOPSIS ^

  use Bio::Community::IO;

  # Read communities from a file, one by one
  my $in = Bio::Community::IO->new(
     -file   => 'otu_table.qiime',
     -format => 'qiime', # format is optional
  );
  my $community1 = $in->next_community(); # a Bio::Community object
  my $community2 = $in->next_community();
  $in->close;

  # Write communities in another file
  my $out = Bio::Community::IO->new(
     -file   => '>new_otu_table.generic',
     -format => 'generic',
  );
  $out->write_community($community);
  $out->close;

  # Re-read communities, but all at once
  $in = Bio::Community::IO->new( -file => 'new_otu_table.generic' );
  my $meta = $in->next_metacommunity(); # a Bio::Community::Meta object
  $in->close;

DESCRIPTION ^

A Bio::Community::IO object implement methods to read and write communities in formats used by popular programs such as BIOM, GAAS, QIIME, Unifrac, or as generic tab-separated tables. The format should be automatically detected though it can be manually specified. This module can also convert community member abundance between counts, absolute abundance, relative abundance and fractions.

When reading communities, the next_member() method is called by next_community(), which itself is called by next_metacommunity(). Similarly, when writing, write_member() is called by write_community(), which is called by write_metacommunity().

DRIVER IMPLEMENTATION

Bio::Community::IO provides the higher-level organisation to read and write community files, but it is the modules located in the Bio::Community::IO::Driver::* namespaces that do the low-level format-specific work.

All drivers are expected to implement specific methods, e.g. for reading:

_next_metacommunity_init()

A private hook called at the beginning of next_metacommunity() that returns the name of the metacommunity (if applicable). It also allows drivers to do an action before the metacommunity is read.

_next_community_init()

A private hook called at the beginning of next_community() that returns the name of the community. It also allows drivers to do an action before the current community is read.

next_member()

A public method that returns a Bio::Community::Member and its count in the community being read.

_next_community_finish()

A private hook called at the end of next_community(). It allows drivers to do an action after the current community has been read.

_next_metacommunity_finish()

A private hook called at the end of next_metacommunity(). It allows drivers to do an action after the metacommunity has been read.

Similarly, for a driver to write community information to a file or stream, it should implement these methods:

_write_metacommunity_init()

A private hook called at the beginning of write_metacommunity() and that accepts a Bio::Community::Meta as argument. It allows drivers to do an action before the metacommunity is written.

_write_community_init()

A private hook called at the beginning of write_community() and that accepts a Bio::Community as argument. It allows drivers to do an action before the current community is written.

write_member()

A public method that accepts as arguments a Bio::Community::Member and its count in the community being written, and processes them.

_write_community_finish()

A private hook called at the end of write_community() and that accepts a Bio::Community as argument. It allows drivers to do an action after the current community has been written.

A private hook called at the end of write_metacommunity() and that accepts a Bio::Community::Meta as argument. It allows drivers to do an action after the metacommunity has been written.

Florent Angly florent.angly@gmail.com

SUPPORT AND BUGS ^

User feedback is an integral part of the evolution of this and other Bioperl modules. 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.

If you have found a bug, please report it on the BioPerl bug tracking system to help us keep track the bugs and their resolution: https://redmine.open-bio.org/projects/bioperl/

COPYRIGHT ^

Copyright 2011-2014 by Florent Angly <florent.angly@gmail.com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

APPENDIX ^

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

new

 Function: Create a new Bio::Community::IO object
 Usage   : # Reading a file
           my $in = Bio::Community::IO->new( -file => 'community.txt' );
           # Writing a file
           my $out = Bio::Community::IO->new( -file => '>community.txt',
                                              -format => 'generic'       );
 Args    : -file : Path of a community file. See file() in Bio::Root::IO.
           -format : Format of the file, either 'generic', 'biom', 'gaas',
               'qiime' or 'unifrac'. This is optional when reading a community
               file because the format is automatically detected by the
               Bio::Community::IO::FormatGuesser module. See also format() in
               Bio::Root::IO.
           -weight_files : Arrayref of files (or filehandles) that contain
               weights to assign to members. See weight_files().
           -weight_assign : When using files of weights, define what to do for
               community members that do not have weights. See weight_assign().
           -taxonomy: Given a Bio::DB::Taxonomy object, try to place the community
               members in this taxonomy. See taxonomy().
           -skip_empty_communities: Skip communities with no members. See
               skip_empty_communities()
           See the documentation for _initialize_io() in Bio::Root::IO for other
           accepted constructors like -fh, -string, -input, or -url.
 Returns : A Bio::Community::IO object

next_member

 Usage   : my ($member, $count) = $in->next_member;
 Function: Get the next member from the community and its abundance. This
           function is implemented by the Bio::Community::IO::Driver used to
           parse the given file format.
 Args    : None
 Returns : An array containing:
             A Bio::Community::Member object (or undef)
             A positive number (or undef)

next_community

 Usage   : my $community = $in->next_community;
 Function: Get the next community. Note that communities without members are
           skipped.
 Args    : None
 Returns : A Bio::Community object
             or
           undef if there were no communities left

next_metacommunity

 Usage   : my $meta = $in->next_metacommunity;
 Function: Get the next metacommunity. It may contain one or several communities
           depending on the format of the file read,
 Args    : None
 Returns : A Bio::Community::Meta object
             or
           undef after the metacommunity has been read

write_member

 Usage   : $out->write_member($member, $abundance);
 Function: Write the next member from the community and its count or relative
           abundance. This function is implemented by a Bio::Community::IO::Driver
           specific to the given file format.
 Args    : A Bio::Community::Member object
           A positive number
 Returns : 1 for success

write_community

 Usage   : $out->write_community($community);
 Function: Write the next community.
 Args    : A Bio::Community object
 Returns : 1 for success

write_metacommunity

 Usage   : $out->write_metacommunity($meta);
 Function: Write a metacommunity.
 Args    : A Bio::Community::Meta object
 Returns : 1 for success

skip_empty_communities

 Usage   : $in->skip_empty_communities;
 Function: Get or set whether empty communities (with no members) should be
           read/written or skipped.
 Args    : 0 or 1
 Returns : 0 or 1

sort_members

 Usage   : $in->sort_members();
 Function: When writing a community to a file, sort the community members based
           on their abundance: 0 (off), 1 (by increasing abundance), -1 (by 
           decreasing abundance). The default is specific to each driver used.
 Args    : 0, 1 or -1
 Returns : 0, 1 or -1

abundance_type

 Usage   : $in->abundance_type();
 Function: When writing a community to a file, report member abundance in one
           of four possible representations:
            * count     : observed count
            * absolute  : absolute abundance
            * percentage: relative abundance, in percent (0-100%)
            * fraction  : relative abundance, as a fractional number (0-1)
           The default is specific to each driver
 Args    : count, absolute, percentage or fraction
 Returns : count, absolute, percentage or fraction

missing_string

 Usage   : $in->missing_string();
 Function: When writing a community to a file, specify what abundance string to
           use for members that are not present in the community. The default is
           specific to each driver used.
 Args    : string e.g. '', '0', 'n/a', '-'
 Returns : string

multiple_communities

 Usage   : $in->multiple_communities();
 Function: Return whether or not the file format can represent multiple
           communities in a single file.
 Args    : 0 or 1
 Returns : 0 or 1

explicit_ids

 Usage   : $in->explicit_ids();
 Function: Return whether or not the file format explicitly records member IDs.
 Args    : 0 or 1
 Returns : 0 or 1

weight_files

 Usage   : $in->weight_files();
 Function: When reading a community, specify files (or filehandles opened in
           read mode) containing weights to assign to the community members.
           Each file can contain a different type of weight to add. The file
           should contain at least two tab-delimited columns: the first one
           should contain the ID, description or string lineage of the member
           and the second one the weight to assign to this member. Other columns
           are ignored. A tab-delimited header line starting with '#' and
           containing the name of the weight can be included.
 Args    : arrayref of file names (or filehandles)
 Returns : arrayref of filehandles

weight_names

 Usage   : $in->weight_names();
 Function: After weight files have been read, you can get the name of the
           weights using this method. You can also set them manually.
 Args    : arrayref of weight names
 Returns : arrayref of weight names

weight_identifier

 Usage   : $in->weight_identifier('id');
 Function: Get or set whether to lookup and assign weights to community members
           based on the member description or their ID.
 Args    : 'desc' (default), or 'id'
 Returns : 'desc' or 'id'

weight_assign

 Usage   : $in->weight_assign();
 Function: When using weights, specify what value to assign to the members for
           which no weight is found in the provided weight file:
            * $num : Check the member description against each file of weights.
                 If no weight is found in a file, assign the arbitrary weight
                 provided as argument to the member.
            * file_average : Check the member description against each file of
                 weights. If no weight is found in a file, assign the average
                 weight in this file to the member.
            * community_average : Check the member description against each file
                 of weights. If no weight is found in a file, the weight given
                 to the member is the average weight of all the other members in
                 in this community. If none of the community members have
                 weights, the weight assignment method defaults to 'file_average'
                 for this community. Note that because the assigned weight is
                 the average weight in this community, this means that the same
                 members will have different weights in different communities.
                 Note also that the processing of members with no explicit
                 weights can only be done after all other members have been
                 added and is effective only if the community is built using the
                 next_community() method.
            * ancestor : Provided the member have a taxonomic assignment, check
                 the taxonomic lineage of this member against each file of
                 weights. When no weight is found for this taxonomic lineage in
                 a weight file, go up the taxonomic lineage of the member and
                 assign to it the weight of the first ancestor that has a
                 weight in the weights file. Fall back to the 'community_average'
                 method if no taxonomic information is available for this member
                 (for example a member with no BLAST hit), or if none of the
                 ancestors have a specified weight.
 Args    : 'file_average', 'community_average', 'ancestor' or a number
 Returns : 'file_average', 'community_average', 'ancestor' or a number

_attach_weights

 Usage   : $in->_attach_weights($member);
 Function: Once a member has been created, a driver should call this method
           to attach the proper weights (read from the user-provided weight
           files) to a member. If no member is provided, this method will not
           complain and will do nothing.
 Args    : a Bio::Community::Member or nothing
 Returns : 1 for success

taxonomy

 Usage   : $in->taxonomy();
 Function: When reading communities, try to place the community members on the
           provided taxonomy (provided taxonomic assignments are specified in
           the input. Make sure that you use the same taxonomy as in the
           community file to ensure that members are placed.
           
           As an alternative to using a full-fledged taxonomy, if you provide a
           Bio::DB::Taxonomy::list object containing no taxa, the taxonomy will
           be constructed on the fly from the taxonomic information provided in
           the community file. The advantages are that you build an arbitrary
           taxonomy, and this taxonomy contains only the taxa present in your
           samples, which is fast and memory efficient. A drawback is that
           unfortunately, you can only do this with community file formats that
           report full lineages (e.g. the qiime and generic formats).

           A basic curation is done on the taxonomy strings, so that a GreenGenes
           lineage such as:
              k__Archaea;p__Euryarchaeota;c__Thermoplasmata;o__E2;f__Marine group II;g__;s__
           becomes:
              k__Archaea;p__Euryarchaeota;c__Thermoplasmata;o__E2;f__Marine group II
           Or a Silva lineage such as:
              Bacteria; Cyanobacteria; Chloroplast; uncultured; Other; Other
           becomes:
              Bacteria; Cyanobacteria; Chloroplast; uncultured

 Args    : Bio::DB::Taxonomy
 Returns : Bio::DB::Taxonomy

_attach_taxon

 Usage   : $in->_attach_taxon($member, $taxonomy_string);
 Function: Once a member has been created, a driver should call this method
           to attach the proper taxon object to the member. If no member is
           provided, this method will not complain and will do nothing.
 Args    : * a Bio::Community::Member or nothing
           * the taxonomic string
           * whether the taxonomic string is a taxon name (1) or taxon ID (0)
 Returns : 1 for success
syntax highlighting: