<commit_before>===============================
Omics Integrator
===============================

Omics Integrator is a package designed to integrate gene expression data and/or
proteomics data using the protein-protein interaction network. It is comprised
of two modules, Garnet and Forest, that perform data integration of various
types of data.

Contact: <NAME> [<EMAIL>], <NAME> [<EMAIL>]

Copyright (c) 2015-2016 <NAME>, <NAME>

Reference:
--------------------
[Network-Based Interpretation of Diverse High-Throughput Datasets through the Omics Integrator Software Package](http://dx.doi.org/10.1371/journal.pcbi.1004879)
<NAME><sup>\*</sup>, Gosline SJC<sup>\*</sup>, <NAME>, <NAME>, <NAME>, <NAME>. *PLoS Comput Biol* 12(4): e1004879. doi:10.1371/journal.pcbi.1004879.

System Requirements:
--------------------
1. Python 2.6 or 2.7 (3.x version currently untested) and the dependencies
below. We recommend that users without an existing Python environment
install Anaconda (https://www.continuum.io/downloads) to obtain Python
2.7 and the following required packages:
  - numpy: http://www.numpy.org/
  - scipy: http://www.scipy.org/
  - matplotlib: http://matplotlib.org/
  - Networkx: http://networkx.github.io

2. msgsteiner package (version msgsteiner-1.1.tgz): http://areeweb.polito.it/ricerca/cmp/code/bpsteiner

3. Boost C++ library: http://www.boost.org

4. Cytoscape for viewing results graphically (tested on versions 2.8-3.2):
http://www.cytoscape.org

Features
--------

* Maps gene expression data to transcription factors using chromatin
  accessibility data

* Identifies proteins in the same pathway as `hits` using protein interaction
  network

* Integrates numerous high throughput data types to determine testable
  biological hypotheses

Installation:
--------------------
Omics Integrator is a collection of Python scripts and data files so can be
easily installed on any system. Steps 1 through 4 are only required for Forest,
and you may skip to step 5 if you will only be running Garnet.

1. Boost is pre-installed on many Linux distributions. If your operating system
does not include Boost, follow the [Boost getting started
guide](http://www.boost.org/doc/libs/1_59_0/more/getting_started/index.html) for
instructions on how to download the library and extract files from the archive.
To use the [Homebrew](http://brew.sh/) package manager for Mac simply type `brew install boost` to install the library.
2. Download `msgsteiner-1.1.tgz` from http://areeweb.polito.it/ricerca/cmp/code/bpsteiner
3. Unpack files from the archive: `tar -xvf msgsteiner-1.1.tgz`
4. Enter the `msgsteiner-1.1` subdirectory and run make
  * See below for advice on compiling the C++ code if you encounter problems. Make a note of the path to the compiled msgsteiner file that was created, which you will use when running Forest.
5. Download the Omics Integrator package: [OmicsIntegrator-0.2.0.tar.gz](./dist/OmicsIntegrator-0.2.0.tar.gz)
6. Unpack files from the archive: `tar -xvzf OmicsIntegrator-0.2.0.tar.gz`
7. Make sure you have all the requirements using the pip tool by entering the
directory and typing: `pip install -r requirements.txt`


  * Some users have reported errors when using this command to install matplotlib. To fix, install matplotlib independently (http://matplotlib.org) or use Anaconda as indicated above.

Now Omics Integrator is installed on your computer and can be used to analyze
your data.

Examples
-----------------
We provide many scripts and files to showcase the various capabilities of Omics
Integrator.  To run this:

1. Download the [example files](./dist/OmicsIntegratorExamples.tar.gz)
2. Unpack by typing `tar -xvzf OmicsIntegratorExamples.tar.gz` in the `dist`
directory.

For specific details about the examples, check out the [README
file](./example/README.md) in the example directory.

Running garnet.py
-----------------

Garnet is a script that runs a series of
smaller scripts to map epigenetic data to genes and then scan the genome to
determine the likelihood of a transcription factor binding the genome near that
gene.

```
Usage: garnet.py [configfilename]

  -s SEED, --seed=SEED  An integer seed for the pseudo-random number
                        generators. If you want to reproduce exact results,
                        supply the same seed. Default = None.


Options:
  -h, --help            show this help message and exit
  --outdir=OUTDIR       Name of directory to place garnet output. DEFAULT:none
  --utilpath=ADDPATH    Destination of chipsequtil library, Default=../src
```

Unlike Forest, the Garnet configuration file is a positional argument and must not
be preceded with `--conf=`.  The configuration file should take the following format:

### garnet input

```
[chromatinData]
#these files contain epigenetically interesting regions
bedfile = bedfilecontainingregions.bed
fastafile = fastafilemappedusinggalaxytools.fasta
#these two files are provided in the package
genefile = ../../data/ucsc_hg19_knownGenes.txt
xreffile = ../../data/ucsc_hg19_kgXref.txt
#distance to look from transcription start site
windowsize = 2000

[motifData]
#motif matrices to be used, data provided with the package
tamo_file = ../../data/matrix_files/vertebrates_clustered_motifs.tamo
#settings for scanning
genome = hg19
numthreads = 4
doNetwork = False
tfDelimiter = .

[expressionData]
expressionFile = tabDelimitedExpressionData.txt
pvalThresh = 0.01
qvalThresh =
```

#### Chromatin Data

Many BED-formatted (`bedfile`) and FASTA-formatted (`fastafile`) files are
included in the examples/ directory. `bedfile` can also be output from MACS
(with a `.xls` extension) or GPS/GEM (with a `.txt` extension).
To use your own epigenetic data, convert to BED and upload the
BED-file to http://usegalaxy.org and select `Fetch Genomic DNA` from the left
menu to click on `Extract Genomic DNA`. This will produce a FASTA-formatted file
that will work with garnet.  We have provided gene (`genefile`) and xref
(`xreffile`)  annotations for both hg19 and mm9 - these files can be downloaded
from http://genome.ucsc.edu/cgi-bin/hgTables if needed. The `windowsize`
parameter determines the maximum distance from a transcription start site to
consider an epigenetic event associated. 2kb is a very conservative metric.

#### motifData

We provide motif data in the proper TAMO format, the user just needs to enter<commit_msg>Update GALAXY instructions<commit_after>===============================
Omics Integrator
===============================

Omics Integrator is a package designed to integrate gene expression data and/or
proteomics data using the protein-protein interaction network. It is comprised
of two modules, Garnet and Forest, that perform data integration of various
types of data.

Contact: <NAME> [<EMAIL>], <NAME> [<EMAIL>]

Copyright (c) 2015-2016 <NAME>, <NAME>

Reference:
--------------------
[Network-Based Interpretation of Diverse High-Throughput Datasets through the Omics Integrator Software Package](http://dx.doi.org/10.1371/journal.pcbi.1004879)
Tuncbag N<sup>\*</sup>, Gosline SJC<sup>\*</sup>, Kedaigle A, Soltis AR, Gitter A, Fraenkel E. *PLoS Comput Biol* 12(4): e1004879. doi:10.1371/journal.pcbi.1004879.

System Requirements:
--------------------
1. Python 2.6 or 2.7 (3.x version currently untested) and the dependencies
below. We recommend that users without an existing Python environment
install Anaconda (https://www.continuum.io/downloads) to obtain Python
2.7 and the following required packages:
  - numpy: http://www.numpy.org/
  - scipy: http://www.scipy.org/
  - matplotlib: http://matplotlib.org/
  - Networkx: http://networkx.github.io

2. msgsteiner package (version msgsteiner-1.1.tgz): http://areeweb.polito.it/ricerca/cmp/code/bpsteiner

3. Boost C++ library: http://www.boost.org

4. Cytoscape for viewing results graphically (tested on versions 2.8-3.2):
http://www.cytoscape.org

Features
--------

* Maps gene expression data to transcription factors using chromatin
  accessibility data

* Identifies proteins in the same pathway as `hits` using protein interaction
  network

* Integrates numerous high throughput data types to determine testable
  biological hypotheses

Installation:
--------------------
Omics Integrator is a collection of Python scripts and data files so can be
easily installed on any system. Steps 1 through 4 are only required for Forest,
and you may skip to step 5 if you will only be running Garnet.

1. Boost is pre-installed on many Linux distributions. If your operating system
does not include Boost, follow the [Boost getting started
guide](http://www.boost.org/doc/libs/1_59_0/more/getting_started/index.html) for
instructions on how to download the library and extract files from the archive.
To use the [Homebrew](http://brew.sh/) package manager for Mac simply type `brew install boost` to install the library.
2. Download `msgsteiner-1.1.tgz` from http://areeweb.polito.it/ricerca/cmp/code/bpsteiner
3. Unpack files from the archive: `tar -xvf msgsteiner-1.1.tgz`
4. Enter the `msgsteiner-1.1` subdirectory and run make
  * See below for advice on compiling the C++ code if you encounter problems. Make a note of the path to the compiled msgsteiner file that was created, which you will use when running Forest.
5. Download the Omics Integrator package: [OmicsIntegrator-0.2.0.tar.gz](./dist/OmicsIntegrator-0.2.0.tar.gz)
6. Unpack files from the archive: `tar -xvzf OmicsIntegrator-0.2.0.tar.gz`
7. Make sure you have all the requirements using the pip tool by entering the
directory and typing: `pip install -r requirements.txt`


  * Some users have reported errors when using this command to install matplotlib. To fix, install matplotlib independently (http://matplotlib.org) or use Anaconda as indicated above.

Now Omics Integrator is installed on your computer and can be used to analyze
your data.

Examples
-----------------
We provide many scripts and files to showcase the various capabilities of Omics
Integrator.  To run this:

1. Download the [example files](./dist/OmicsIntegratorExamples.tar.gz)
2. Unpack by typing `tar -xvzf OmicsIntegratorExamples.tar.gz` in the `dist`
directory.

For specific details about the examples, check out the [README
file](./example/README.md) in the example directory.

Running garnet.py
-----------------

Garnet is a script that runs a series of
smaller scripts to map epigenetic data to genes and then scan the genome to
determine the likelihood of a transcription factor binding the genome near that
gene.

```
Usage: garnet.py [configfilename]

  -s SEED, --seed=SEED  An integer seed for the pseudo-random number
                        generators. If you want to reproduce exact results,
                        supply the same seed. Default = None.


Options:
  -h, --help            show this help message and exit
  --outdir=OUTDIR       Name of directory to place garnet output. DEFAULT:none
  --utilpath=ADDPATH    Destination of chipsequtil library, Default=../src
```

Unlike Forest, the Garnet configuration file is a positional argument and must not
be preceded with `--conf=`.  The configuration file should take the following format:

### garnet input

```
[chromatinData]
#these files contain epigenetically interesting regions
bedfile = bedfilecontainingregions.bed
fastafile = fastafilemappedusinggalaxytools.fasta
#these two files are provided in the package
genefile = ../../data/ucsc_hg19_knownGenes.txt
xreffile = ../../data/ucsc_hg19_kgXref.txt
#distance to look from transcription start site
windowsize = 2000

[motifData]
#motif matrices to be used, data provided with the package
tamo_file = ../../data/matrix_files/vertebrates_clustered_motifs.tamo
#settings for scanning
genome = hg19
numthreads = 4
doNetwork = False
tfDelimiter = .

[expressionData]
expressionFile = tabDelimitedExpressionData.txt
pvalThresh = 0.01
qvalThresh =
```

#### Chromatin Data

Many BED-formatted (`bedfile`) and FASTA-formatted (`fastafile`) files are
included in the examples/ directory. `bedfile` can also be output from MACS
(with a `.xls` extension) or GPS/GEM (with a `.txt` extension).
To use your own epigenetic data, convert to BED and upload the
BED-file to http://usegalaxy.org and select `Fetch Alignments/Sequences` from the left
menu to click on `Extract Genomic DNA`. This will produce a FASTA-formatted file
that will work with garnet.  We have provided gene (`genefile`) and xref
(`xreffile`)  annotations for both hg19 and mm9 - these files can be downloaded
from http://genome.ucsc.edu/cgi-bin/hgTables if needed. The `windowsize`
parameter determines the maximum distance from a transcription start site to
consider an epigenetic event associated. 2kb is a very conservative metric.

#### motifData

We provide motif data in the proper TAMO format, the user just needs to enter
{'fraction_non_alphanumeric': 0.10463483146067416, 'fraction_numerical': 0.017166042446941324, 'mean_word_length': 3.9182655410590943, 'pattern_counts': {'":': 0, '<': 28, '<?xml version=': 0, '>': 28, 'https://': 2, 'lorem ipsum': 0, 'www.': 12, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '549358', 'n_tokens_mistral': 3900, 'n_tokens_neox': 3584, 'n_words': 1543}