SYNOPSIS
use Bio::DB::BigSet;
use Bio::DB::BigWig 'binMean';
my $wigset = Bio::DB::BigWigSet->new(-dir => $dir,
-feature_type => 'summary'
);
my $iterator = $wigset->get_seq_stream(-seq_id => 'I',
-start => 100,
-end => 1000,
-type => 'binding_site');
while (my $summary = $iterator->next_seq) {
my $arry = $summary->statistical_summary(100);
print binMean($_),"\n" foreach @$arry;
}DESCRIPTION
This module provides a convenient way of adding metadata to a directory of BigWig files in such a way that it appears that all the BigWig files form a single database of sequence features. The directory should be layed out so that it contains one or more BigWig files and a metadata index file that adds names and attributes to the files.
The metdata file must be named beginning "meta". Anything following the initial ``meta'' is fine. Its format is described below. The metadata file is optional if the BigWig files end with the extension ".bw", in which case they will be added to the collection automatically
The metadata file is plain text and should be laid out like this:
[file1.bw]
display_name = foobar
type = some_type1
method = my_method1
source = my_source1
some_attribute = value1
another_attribute = value2
[file2.bw]
display_name = barfoo
type = some_type2
method = my_method2
source = my_source2
some_attribute = value3
another_attribute = value4
...Each stanza begins with the name of one of the bigwig files in the directory, enclosed by brackets. Following this are a series of "attribute = value pairs" which will be applied to features returned from the corresponding BigWig file. The following attributes have predefined meanings:
Attribute Value
--------- -----
display_name The value returned by each feature's display_name()
method.
name An alias for display_name.
type The value returned by each feature's type() method
(this method will return "$method:$source" if
type is not defined).
primary_tag The value returned by each feature's primary_tag()
and method () methods.
method An alias for primary_tag.
source The value returned by each feature's source() and
source_tag() methods.Any other attributes are stored in the feature and can be retrieved with the get_all_tags(), get_tag_values() and attributes() methods. See Bio::SeqFeatureI and Bio::SeqFeature::Lite.
Any bigwig files that are present in the directory but not mentioned in the metdata file will be assigned a display_name equal to the name of the file, minus the .bw extension.
The point of this is to allow you to make a set of BigWig files act like a uniform database, and to assign distinguishing types, names and attributes to the features returned to the file.
For example, if one of the WigFiles is assigned a type of "polII_binding_site:early_embryo" using a stanza like this:
[random_wigfile.bw]
type = polII_binding_site:early_embryoYou can fetch it from the BigWigSet using this call:
my @summaries = $bigwigset->features(-seq_id=>'chr1',
-start =>1,-end=>50_000_000,
-type => 'polII_binding_site:early_embryo');See Bio::DB::SeqFeature::Store for more examples of this API.
The directory of BigWigs may be on a remote HTTP or FTP server; simply provide the URL for the remote directory. This will only work if the remote server allows directory listings.
METHODS
Most methods are inherited from Bio::DB::BigWig (see Bio::DB::BigWig). This section describes the differences.
Class Methods
- $bws = Bio::DB::BigWigSet->new('/path/to/directory')
- $bws = Bio::DB::BigWigSet->new(-dir => '/path/to/directory', -feature_type => $type, -fasta => $fasta_file_or_obj)
- $bws = Bio::DB::BigWigSet->new(-index => '/path/to/metadata.txt')
-
This method creates a new Bio::DB::BigWigSet. If just one argument is provided, it is used as the path to the directory where the BigWig files are stored. In the named-argument form, the following arguments are recognized:
Argument Description -------- ----------- -dir Path to the directory containing wigfiles and metadata. -fasta A Fasta file path or a sequence accessor to pass to each of the BigWig files when they are open. See the Bio::DB::BigWig manual page for more information. -feature_type The type of feature to retrieve from the BigWig files. One of "summary", "bin", "region" or "interval." See the Bio::DB::BigWig manual page for more information. If not specified "summary" is assumed. -index Provide a path to the metadata file directly.You may call new() without any arguments, in which case an empty BigWig set is created. You may add BigWig files to the set individually using add_bigwig().
- $count = Bio::DB::BigWig->index_dir($path/to/dir)
-
Given a directory, this class method creates a skeletal metadata file named "metadata.index" from any bigwig fies it finds in the directory. You should customize this file as needed. If the method is called on a directory that already contains one or more metadata files then it will leave intact any stanzas that correspond to existing SAM tiles, add new stanzas for bigwigs that are not mentioned in the index, and remove stanzas that no longer correspond to a WIG file.
Also see the index_bigwigset.pl script that comes with the distribution.
Accessors
These are accessors for BigWigSet properties.
- $fasta = $bws->fasta_path([$new_path])
-
Get or set the FASTA file path or sequence accessor.
- $type = $bws->feature_type([$new_type])
-
Get or set the underlying type of object that the BigWig set will return. One of "summary", "bin", "region" or "interval". See Bio::DB::BigWig.
- $accessor = $bws->dna_accessor()
-
Returns the object that will be used to access DNA sequences, if a -fasta argument was providd at create time.
Fetching Features
These are methods used to query the collection of BigWig files managed by the BigWigSet for various kinds of features. They are similar to the like-named methods in Bio::DB::BigWig.
- @features = $bigwig->features(@args)
-
This method is the workhorse for retrieving various types of intervals and summary statistics from the BigWig database. It takes a series of named arguments in the format (-argument1 => value1, -argument2 => value2, ...) and returns a list of zero or more BioPerl Bio::SeqFeatureI objects.
The following arguments are recognized:
Argument Description Default -------- ----------- ------- -seq_id Chromosome or contig name defining All chromosomes/contigs. the range of interest. -start Start of the range of interest. 1 -end End of the range of interest Chromosome/contig end -type Retrieve only features with the none matching type(s). The argument can be a scalar or an arrayref. -name Retrieve only features with the none indiccated name. -attributes Retrieve only features that have none matching attributes. The argument is a hashref of tag value attributes, in which the key is the tag and the value is either a simple value, or an array reference of values. -iterator Boolean, which if true, returns undef (false) an iterator across the list rather than the list itself.The features() method is similar to that of Bio::DB::BigWig, but some of the arguments have slightly different meanings.
-type is a selector that filters the features returned by the type specified in their metadata. You can provide a single value, or an arrayref of several types to filter by. Only BigWig files whose type, as set in the metadata index, match one or more of the provided types will be consulted for features. The behavior of the features -- whether they represent individal wiggle intervals, summaries, or bins is set by the -feature_type argument passed to the BigWigSet->new() method.
The -attributes argument will filter BigWig data by any combination of metadata tag. Here's how it works:
@features = $bws->features(-seq_id => 'chr1', -attributes => {method => ['ChIP-seq','ChIP-chip'], validated => 1});This will query BigWig files from the set whose metadata indicates a method of either "ChIP-seq" or "ChIP-chip" and which have a "validated" attribute of 1. GLOB matches, such as "ChIP*" are also accepted.
The features returned from this call will return values from display_name(), primary_tag(), source_tag(), and get_tag_values() that correspond to the information specified in the metadata index. For example, the features returned from the example query above, will return either "ChIP-seq" or "ChIP-chip" when you call:
$method = $feature->get_tag_values('method'); - $iterator = $bws->get_seq_stream(@args)
-
This call takes the same arguments as features() but returns a memory-efficient iterator. Call the iterator's next_seq() method repeatedly to fetch the features one at a time.
- @features = $bws->get_features_by_location($seq_id,$start,$end)
-
Same as in Bio::DB::BigWig, except that features from all members of the set are returned.
- @features = $bws->get_features_by_name($name)
- @features = $bws->get_feature_by_name($name)
- @features = $bws->get_features_by_alias($name)
-
Only features from BigWig files whose display_name attribute matches $name will be returned. These three methods all do the same thing.
- @features = $bws->get_features_by_attribute($attributes)
-
Only features matching the attributes hash will be returned. See features() for a description of how this filter works.
- $feature = $bws->get_features_by_id($id)
-
Given an ID returned by calling a feature's primary_id() method this returns the same feature. If used between sessions, it only works as expected if the BigWigSet is created in the same way each time.
Methods for manipulating the BigWig files contained in the set
These are methods that allow you to add BigWig files to the set and manipulate their metadata.
- $bws->readdir($path)
-
Read the contents of the indicated directory, and combine the information about the BigWig .bw files and metadata indexes into a BigWig set. You may call this repeatedly to combine multiple directories into a BigWigSet.
- $bws->add_bigwig($path)
-
Given a path to a .bw file, add the BigWig file to the set.
- $bws->remove_bigwig($path)
-
Given a path to a .bw file, removes it from the set.
- $bws->set_bigwig_attributes($path,$attributes)
-
Given the path to a BigWig file, assign metadata to it. The second argument is a hash in which the keys are attribute names such as "type" and the values are the values of those attributes.
If the BigWig file is not already part of the set, it is added (as in add_bigwig()).
- @paths = $bws->bigwigs
-
Returns the path to all the BigWig files in the collection.
- $bigwig = $bws->get_bigwig($path)
-
If the BigWig file is part of the set, opens and returns it.
Using BigWig objects and GBrowse
The Generic Genome Browser version 2.0 (http://www.gmod.org/gbrowse) can treat a BigWig file as a track database. A typical configuration will look like this:
[BigWig:database]
db_adaptor = Bio::DB::BigWigSet
db_args = -dir /var/www/data/bigwigs
-fasta /var/www/data/elegans-ws190.fa
[BigWigIntervals]
feature = ChIP-chip
database = BigWig
glyph = wiggle_whiskers
min_score = -1
max_score = +1.5
key = ChIP-chip datasetsSEE ALSO
Bio::DB::BigWig Bio::DB::BigFile, Bio::Perl, Bio::Graphics, Bio::Graphics::Browser2
AUTHOR
Lincoln Stein <lincoln.stein@oicr.on.ca>. <lincoln.stein@bmail.com>
Copyright (c) 2010 Ontario Institute for Cancer Research.
This package and its accompanying libraries is free software; you can redistribute it and/or modify it under the terms of the GPL (either version 1, or at your option, any later version) or the Artistic License 2.0. Refer to LICENSE for the full license text. In addition, please see DISCLAIMER.txt for disclaimers of warranty.