#################################
##                             ##
##    BiasAway version 0.96    ##
##        08/12/2017           ##
##                             ##
#################################

We provide here the README of the BiasAway software developed in Python. The
software provides a user with four approaches for generating a background
useful to enrichment analyses:
    1) mononucleotide shuffled target sequence to preserve the mononucleotide
       composition of the target sequences,
    2) dinucleotide shuffled target sequence to preserve the dinucleotide
       composition of the target sequences,
    3) genomic sequences matched to the mononucleotide composition of each
       target sequence to preserve the non-random association of nucleotides,
    4) sliding window of mononucleotide shuffled target sequence,
    5) sliding window of dinucleotide shuffled target sequence, 
    6) genomic sequences matched in windows of internal mononucleotide
       composition for each target sequence.
The latter three backgrounds (BiasAway 4-6) are variants of the former three
backgrounds (BiasAway 1-3), in which we utilized a sliding window over the
ChIP-Seq sequences to determine a distribution for local regions of
composition. The background sequence set is then generated (mono- or
di-nucleotide shuffle) or selected from a pool of genomic sequences (genomic
composition match) to match the distribution of window compositions for each
target sequence. These latter backgrounds were considered because due to
evolutionary changes such as insertion of repetitive sequences, local
rearrangements, or biochemical missteps, the target sequences may have
sub-regions of distinct nucleotide composition.

You can get more information by reading the associated manuscript 
R. Worsley-Hunt et al., Improving detection and analysis of transcription
factor binding sites within ChIP-Seq data, 2014, under revision.


###############################################################################
Authors: Anthony Mathelier, Luis del Peso, Rebecca Worsley-Hunt,
         and Wyeth W. Wasserman
         Centre for Molecular Medicine and Therapeutics
         950 West 28th Avenue
         Vancouver, BC
         V5Z 4H4 Canada

         [email protected]
         [email protected]
         [email protected]
         [email protected]

         Refer to the AUTHORS file.


###############################################################################
System requirements:

* Python should be installed on your machine (only version 2.7 has been
        tested).
* Biopython should be installed. See
    http://biopython.org for instructions on how to install it.


###############################################################################
Download:

The BiasAway software is available as open source code from GitHub
https://github.com/wassermanlab/BiasAway.


###############################################################################
Usage:

To get the help on how to use the software, you can run:
    $ python BiasAway -h
Help for each specific way of generating background can be obtain by typing:
    $ python BiasAway m -h
or  $ python BiasAway f -h
or  $ python BiasAway d -h
or  $ python BiasAway w -h
or  $ python BiasAway g -h
or  $ python BiasAway c -h

Note that "BiasAway g" and "bBiasAway c" ask for a background repository, a
background file can also be giving optionally. If the background repository
contains files corresponding to %GC bins, the software will use these files and
ignore any other background file. If the background repository is empty,
sequences from the background files will be used and %GC bins files will be
constructed and stored in the background directory for further usage.
Using pre-computed %GC bins files help in speeding up the background generation
process.
Preprocessed background repositories can be found at:
http://cisreg.cmmt.ubc.ca/BiasAway_background/


###############################################################################
Reference:

The BiasAways software have been described in R. Worsley-Hunt et al., Improving
detection and analysis of transcription factor binding sites within ChIP-Seq
data, 2014, under revision.
Please cite this publication when using BiasAway.


###############################################################################
Licence:

* BiasAways has been developed under the GNU Lesser General Public Licence (see
    http://www.gnu.org/copyleft/lesser.html).