NAME

get_binned_data.pl

A program to collect data in bins across a list of features.

SYNOPSIS

 get_binned_data.pl [--options] <filename>
  
  Options for existing files:
  --in <filename>
  
  Options for new files:
  --db <name | filename>
  --feature <type | type:source | alias>, ...
  
  Options for data collection:
  --ddb <name | filename>
  --data <dataset_name | filename>
  --method [mean|median|stddev|min|max|sum|rpm]             (mean)
  --value [score|count|pcount|length]                       (score)
  --strand [all|sense|antisense]                            (all)
  --force_strand
  --long
  --(no)log
  
  Bin specification:
  --bins <integer>                                          (10)
  --ext <integer>                                           (0)
  --extsize <integer>
  --min <integer>
  
  Post-processing:
  --sum
  --smooth
  
  General options:
  --out <filename>
  --gz
  --cpu <integer>                                           (2)
  --version
  --help

OPTIONS

The command line flags and descriptions:

--in <filename>

Specify an input file containing either a list of database features or genomic coordinates for which to collect data. The file should be a tab-delimited text file, one row per feature, with columns representing feature identifiers, attributes, coordinates, and/or data values. The first row should be column headers. Bed files are acceptable, as are text files generated by other BioToolBox scripts. Files may be gzipped compressed.

--db <name | filename>

Specify the name of a Bio::DB::SeqFeature::Store annotation database from which gene or feature annotation may be derived. A database is required for generating new data files with features. This option may skipped when using coordinate information from an input file (e.g. BED file), or when using an existing input file with the database indicated in the metadata. For more information about using annotation databases, see https://code.google.com/p/biotoolbox/wiki/WorkingWithDatabases.

--feature <type | type:source | alias>,...

Specify the type of feature from which to collect values. This is required only for new feature tables. Three types of values may be passed: the feature type, feature type and source expressed as 'type:source', or an alias to one or more feature types. Aliases are specified in the biotoolbox.cfg file and provide a shortcut to a list of one or more database features. More than one feature may be included as a comma-delimited list (no spaces).

--ddb <name | filename>

If the data to be collected is from a second database that is separate from the annotation database, provide the name of the data database here. Typically, a second Bio::DB::SeqFeature::Store or BigWigSet database is provided here.

--data <dataset_name | filename>

Provide the name of the dataset to collect the values. If no dataset is specified on the command line, then the program will interactively present a list of datasets from the database to select.

The dataset may be a feature type in a BioPerl Bio::DB::SeqFeature::Store or Bio::DB::BigWigSet database. Provide either the feature type or type:source. The feature may point to another data file whose path is stored in the feature's attribute tag (for example a binary Bio::Graphics::Wiggle .wib file, a bigWig file, or Bam file), or the features' scores may be used in data collection.

Alternatively, the dataset may be a database file, including bigWig (.bw), bigBed (.bb), or Bam alignment (.bam) files. The files may be local or remote (specified with a http: or ftp: prefix).

--method [mean|median|stddev|min|max|range|sum|rpm]

Specify the method for combining all of the dataset values within the genomic region of the feature. Accepted values include:

• mean (default)

• median

• sum

• stddev Standard deviation of the population (within the region)

• min

• max

• range Returns difference of max and min

• rpm Reads Per Million mapped, Bam/BigBed only

--value [score|count|pcount|length]

Optionally specify the type of data value to collect from the dataset or data file. Four values are accepted: score, count, pcount, or length. The default value type is score. Note that some data sources only support certain types of data values. The types are detailed below.

• score

  The default value. Supported by wig, bigWig, USeq, bigBed (if the features include the score column), GFF features, and Bam (returns non-transformed base pair coverage).

• count

  Counts the number of features that overlap the search region. For long features (> 1 bp), these may include features that overlap or span beyond the search region. Supported by all databases.

• pcount (precise count)

  Counts only those features that are contained within the search region, not overlapping. Supported by Bam, bigBed, USeq, and GFF features.

• length

  Returns the length of long features. Supported by Bam, bigBed, USeq, and GFF features.

--strand [all|sense|antisense]

Specify whether stranded data should be collected. Three values are allowed: all datasets should be collected (default), only sense datasets, or only antisense datasets should be collected.

--force_strand

For features that are not inherently stranded (strand value of 0) or that you want to impose a different strand, set this option when collecting stranded data. This will reassign the specified strand for each feature regardless of its original orientation. This requires the presence of a "strand" column in the input data file. This option only works with input file lists of database features, not defined genomic regions (e.g. BED files). Default is false.

--long

Indicate that the dataset from which scores are collected are long features (counting genomic annotation for example) and not point data (microarray data or sequence coverage). Normally long features are only recorded at their midpoint, leading to inaccurate representation at some windows. This option forces the program to collect data separately at each window, rather than once for each file feature or region and subsequently assigning scores to windows. Execution times may be longer than otherwise. Default is false.

--(no)log

Dataset values are (not) in log2 space and should be treated accordingly. Output values will be in the same space.

--bins <integer>

Specify the number of bins that will be generated over the length of the feature. The size of the feature is a percentage of the feature length. The default number is 10, which results in bins of size equal to 10% of the feature length.

--ext <integer>

Specify the number of extended bins on either side of the feature. The bins are of the same size as determined by the feature length and the --bins value. The default is 0.

--extsize <integer>

Specify the exact bin size in bp of the extended bins rather than using a percentage of feature of length.

--min <integer>

Specify the minimum feature size to be averaged. Features with a length below this value will not be skipped (all bins will have null values). This is to avoid having bin sizes below the average microarray tiling distance. The default is undefined (no limit).

--sum

Indicate that the data should be averaged across all features at each position, suitable for graphing. A separate text file will be written with the suffix '_summed' with the averaged data. The default is false.

--smooth

Indicate that windows without values should (not) be interpolated from neighboring values. The default is false.

--out <filename>

Specify the output file name.

--gz

Specify whether (or not) the output file should be compressed with gzip.

--cpu <integer>

Specify the number of CPU cores to execute in parallel. This requires the installation of Parallel::ForkManager. With support enabled, the default is 2. Disable multi-threaded execution by setting to 1.

--version

Print the version number.

--help

This help text.

DESCRIPTION

This program will collect data across a gene or feature body into numerous percentile bins. It is used to determine if there is a spatial distribution preference for the dataset over gene bodies. The number of bins may be specified as a command argument (default 10). Additionally, extra bins may be extended on either side of the gene (default 0 on either side). The bin size is determined as a percentage of gene length.

The program writes out a tim data formatted text file. It will also optionally generate a summary or average profile for all of the features.

EXAMPLES

These are some examples of some common scenarios for collecting data.

Collect scores in intervals

You want to collect the mean score from a bigWig file in 10% intervals across each feature in a Bed file.

  get_binned_data.pl --data scores.bw --in input.bed

Collect scores in intervals plus extended regions

You want to collect the maximum score in 5% intervals across each each feature as well as five 100 bp intervals outside of each interval.

  get_binned_data.pl --bins 20 --method max --ext 5 --extsize 100 --data \
  scores.bw --in input.txt

Collect scores in intervals for genes

You want to collect stranded alignment counts from a Bam file for genes in an annotation database, then generate a profile graph.

  get_binned_data.pl --db annotation --feature gene --strand sense --value \
  count --method sum --data alignments.bam --out gene_profile --sum
  
  graph_profile.pl --in gene_profile_summed.txt --min 0 --max 100

AUTHOR

 Timothy J. Parnell, PhD
 Howard Hughes Medical Institute
 Dept of Oncological Sciences
 Huntsman Cancer Institute
 University of Utah
 Salt Lake City, UT, 84112

This package is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.