empanada 0.0.3
EMPANADA: a tool for evidence-based assignment of genes to pathways in metagenomic data


======================
EMPANADA Documentation
======================

EMPANADA is a tool for evidence-based assignment of genes to pathways in metagenomic data,
developed and maintained by the Borenstein group at the University of Washington.

============
Availability
============

EMPANADA is available as a Python module from GitHub or PyPI (see installation instructions below)

=======
License
=======

EMPANADA is distributed under a non-commercial license (see LICENSE).

=========================
Installation Instructions
=========================

Prerequisites for installing:

In order for EMPANADA to run successfully, the following Python modules should be pre-installed on your system:

- Numpy >= 1.16.0 (http://www.numpy.org/)
- Pandas >= 0.14 (http://pandas.pydata.org/)

If you have *pip* installed, you can install these packages by running the following command:

``pip install -U numpy pandas``

**Installing EMPANADA:**

To install EMPANADA, download the package from https://github.com/borenstein-lab/empanada/archive/0.0.3.tar.gz

After downloading EMPANADA, you’ll need to unzip the file. If you’ve downloaded the release version, do this with the following command:

``tar -xzf empanada-0.0.3.tar.gz``

You’ll then change into the new EMPANADA directory as follows:

``cd empanada-0.0.3``

and install using the following command:

``python setup.py install``

ALTERNATIVELY, you can install EMPANADA directly from PyPI by running:

``pip install -U empanada``

============================
Testing the software package
============================

After downloading and installing the software, we recommend testing it by running the following command:

``test_empanada.py``

This will invoke a series of tests. A correct output should end with:

``Ran 1 tests in X.XXXXs``

``OK``

=================================
EMPANADA API via the command line
=================================
The EMPANADA module handles all calculations internally.
EMPANADA offers an interface to the EMPANADA functionality via the command line and the run_empanada script.

Usage:
------

``run_empanada.py -ko KO_ABUNDANCE_FILE -ko2path KO_TO_PATHWAY_FILE [options]``

Required arguments:
-------------------

**-ko KO_ABUNDANCE_FILE**
    Input KO abundance file to aggregate to pathway abundance

**-ko2path KO_TO_PATHWAY_FILE**
    Input file of KO-to-pathway mapping

Optional arguments:
-------------------

**-h, --help**
    show help message and exit

**-o, --output**,
    Output file for resulting pathway abundance (default: out.tab)

**-oc, --output_counts**,
    Output file for number of KOs mapped to each pathway (default: counts.tab)

**-om, --output_mapping**,
    Output the mapping table (either given or generated) to file, works only with pooled mappings (default: mapping.tab)

**-map {naive, by_support, by_sum_abundance, by_avg_abundance}, --mapping_method {naive, by_support, by_sum_abundance, by_avg_abundance}**
    Method to map KOs to Pathway (default: naive)

**-compute {sum}, --compute_method {sum}**
    Method to compute pathway abundance from mapped KOs (default: sum)

**-threshold, --abundance_threshold**
    Abundance threshold to include KOs (default: 0.0)

**-fraction, --fractional_ko_contribution**
    Divide KO contributions such that they sum to 1 for each KO (default: False)

**-remove_ko_with_no_pathway**
    Remove KOs with no pathway from analysis (default: False)

**-remove_ko_with_no_abundance_measurement**
    Remove KOs with no measurements in the abundance table from analysis (default: False)

**-transpose_ko, --transpose_ko_abundance**
    Transpose the ko abundance matrix given (default: False)

**-transpose_output, --transpose_output**
    Transpose the output pathway abundance matrix (default: False)

**-permute_ko_mapping**
    Permute the given KO mapping, i.e., which KO map to which pathways for hypothesis testing (default: False)

**-use_only_non_overlapping_genes**
    If the mapping is by_abundance, compute pathway support by only using non-overlapping genes (default: False)

**-pool_samples_use_median**
    If the mapping is by_abundance, pool samples together using the median KO abundance, and learn the mapping only once (default: False)

**-pool_samples_use_average**
    If the mapping is by_abundance, pool samples together using the average KO abundance, and learn the mapping only once (default: False)

**-leave_one_ko_out_pathway_support**
    If the mapping is by_abundance, compute pathway support for each KO separately by removing it from the computation (default: False)

**-compute_support_with_weighted_double_counting**
    If the mapping is by_abundance, double count KO abundance (weighted by mapping) when computing pathway support (default: False)

**-v, --verbose**
    Increase verbosity of module (default: False)


========
Examples
========

In the *empanada/examples* directory, the file *simulated_ko_relative_abundance.tab* contains simulated KO abundance measurements of 20 samples.
Using this file as input for EMPANADA results in the following files:

- pathway_abundance_empanada.tab

The command used are the following (via command line):

``run_empanada.py -ko examples/simulated_ko_relative_abundance.tab -ko2path data/KOvsPATHWAY_BACTERIAL_KEGG_2013_07_15.tab -o examples/pathway_abundance_empanada.tab -threshold 0 -map by_avg_abundance -fraction -leave_one_ko_out_pathway_support -use_only_non_overlapping_genes``

==================
Citing Information
==================

If you use the EMPANADA software, please cite the following paper:

Functional variability in the human microbiome: More than meets the eye
**Ohad Manor and Elhanan Borenstein.** *In preparation*



=======
HISTORY
=======

=======================
0.0.3 (6 January, 2020)
=======================
* Fixed deprecated numpy usage
* Updating numpy version requirement to >=1.16.0

========================
0.0.1 (9 February, 2016)
========================
* Initial release of beta version


=======
Authors
=======

EMPANADA is written and maintained by Ohad Manor and the Borenstein group in University of Washington.





EMPANADA Software License Agreement

EMPANADA (C) 2014-2016, University of Washington. All rights reserved.

Subject to the terms below, the University of Washington ("UW"), Professor Elhanan Borenstein, and Ohad Manor ("Developer(s)") give permission for you and other members of your laboratory for as long as they remain members ("Academic User(s)"), such permission granted solely to Academic Users in a nonprofit institution of higher education or a nonprofit research institution ("University"),  to use EMPANADA solely as further detailed below. EMPANADA is a tool for evidence-based assignment of genes to pathways in metagenomic data. EMPANADA is protected by a copyright. The National Institutes of Health supported work on EMPANADA. The UW and the Developers allow Academic Users to perform, copy, and modify EMPANADA, solely for internal, non-profit academic research purposes, and as long as Academic Users comply with the terms of this EMPANADA Software License Agreement:

1. EMPANADA is not used for any commercial purposes, or as part of a system which has commercial purposes. The EMPANADA software remains at your University and is not published, distributed, or otherwise transferred or made available to other than Academic Users.

2. You may not distribute EMPANADA or any modification to EMPANADA to any third party.

If you wish to obtain EMPANADA software for any commercial purposes, you will need to contact the University of Washington to see if rights are available and to negotiate a commercial license and pay a fee among other requirements. This includes, but is not limited to, using EMPANADA to provide services to outside parties for a fee. In that case please contact:

UW CoMotion
University of Washington
4311 11th Ave. NE,
Suite 500 Seattle, WA 98105-4608
Phone: (206) 543-3970
Email: license@uw.edu

3. You retain in EMPANADA and any modifications to EMPANADA, the copyright, trademark, patent or other notices pertaining to EMPANADA as provided by UW.

4. You acknowledge that the Developers, the UW and its licensees may develop modifications to EMPANADA that may be substantially similar to your modifications of EMPANADA, and that the Developers, UW and its licensees shall not be constrained in any way by you in UW's or its licensees' use or management of such modifications. You acknowledge the right of the Developers and UW to prepare and publish modifications to EMPANADA that may be substantially similar or functionally equivalent to your modifications and improvements, and if you obtain patent protection for any modification or improvement to EMPANADA you agree not to allege or enjoin infringement of your patent by the Developers, the UW or by any of UW's licensees obtaining modifications or improvements to EMPANADA from the University of Washington or the Developers.

5. If utilization of the EMPANADA software results in outcomes which will be published, you will specify the version of EMPANADA you used and cite the UW Developers.

6. Any risk associated with using the EMPANADA software at your organization is with you and your organization. EMPANADA is experimental in nature and is made available as a research courtesy "AS IS," expressly without any obligation by UW to provide accompanying services or support.

7. UW AND THE DEVELOPERS EXPRESSLY DISCLAIM ANY AND ALL WARRANTIES REGARDING THE SOFTWARE, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES PERTAINING TO MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

8. This Software License Agreement and all rights granted under it terminate on December 31st, 2020. Upon termination, you agree to remove so as to make unrecoverable the original EMPANADA software, all copies and all modifications thereof.