Metadata-Version: 2.4
Name: AmpliconSuiteAggregator
Version: 6.1.0
Summary: Aggregator tool for multiple Amplicon Architect outputs
Author-email: Thorin Tabor <tmtabor@cloud.ucsd.edu>, Jens Luebeck <jluebeck@ucsd.edu>
License: ----------------------------------------------------------------
               *** GENEPATTERN LICENSE AGREEMENT ***
                           
        ----------------------------------------------------------------
        GenePattern is distributed under the following BSD-style license:
                                    
        Copyright (c) 2003-2022 Regents of the University of California. All rights reserved.
                                    
        Redistribution and use in source and binary forms, with or without modification, 
        are permitted provided that the following conditions are met:
                                    
             1. Redistributions of source code must retain the above copyright notice, 
                this list of conditions and the following disclaimer.
                                    
             2. Redistributions in binary form must reproduce the above copyright notice, 
                this list of conditions and the following disclaimer in the documentation 
                and/or other materials provided with the distribution.
                                    
             3. Neither the names of the Regents of the University of California 
                nor the names of its contributors may be used to endorse or promote products derived 
                from this software without specific prior written permission.
                                    
        THIS SOFTWARE IS PROVIDED AS IS.  REGENTS OF THE UNIVERSITY OF CALIFORNIA MAKE NO EXPRESS OR IMPLIED 
        REPRESENTATIONS OR WARRANTIES OF ANY KIND REGARDING THE SOFTWARE AND COPYRIGHT, 
        INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 
        PARTICULAR PURPOSE, CONFORMITY WITH ANY DOCUMENTATION, NONINFRINGEMENT, OR THE 
        ABSENCE OF LATENT OR OTHER DEFECTS, WHETHER OR NOT DISCOVERABLE. IN NO EVENT SHALL
        REGENTS OF THE UNIVERSITY OF CALIFORNIA, THE COPYRIGHT HOLDERS, OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
        INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
        BUT NOT LIMITED TO PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 
        OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
        WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF, HAVE REASON 
        TO KNOW, OR IN FACT SHALL KNOW OF THE POSSIBILITY OF SUCH DAMAGE.
                                    
        If, by operation of law or otherwise, any of the aforementioned warranty disclaimers 
        are determined inapplicable, your sole remedy, regardless of the form of action, 
        including, but not limited to, negligence and strict liability, shall be replacement
        of the software with an updated version if one exists.
        
Project-URL: Homepage, https://github.com/AmpliconSuite/AmpliconSuiteAggregator
Project-URL: Issues, https://github.com/AmpliconSuite/AmpliconSuiteAggregator/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Amplicon Suite Aggregator

## Description
Aggregates results from [AmpliconSuite-pipeline](https://github.com/AmpliconSuite/AmpliconSuite-pipeline) runs.
- Accepts compressed input files (`.tar.gz`, `.zip`) of individual or grouped AmpliconSuite results, or plain directories.
- Aggregates and packages results into a new `.tar.gz` file, along with an aggregated `.csv` and `.html` summary.
- The output `.tar.gz` can be directly uploaded to [AmpliconRepository.org](https://AmpliconRepository.org).
- Supports batch sample renaming via a name map file.
- Can include auxiliary files alongside the upload; place them in a directory containing a file named `AUX_DIR`.

## Installation

**Option 1 — pip**
```bash
pip install AmpliconSuiteAggregator
```

**Option 2 — Git clone**
```bash
git clone https://github.com/AmpliconSuite/AmpliconSuiteAggregator.git
cd AmpliconSuiteAggregator
pip install -r requirements.txt
```

## Dependencies
Python packages: `pandas`, `requests`

## Usage

```bash
python src/AmpliconSuiteAggregator.py -flist <input_list.txt> -o <project_name> [options]
```

`input_list.txt` is a plain text file with one input path per line (`.tar.gz`, `.zip`, or directory).

### Aggregation options

| Flag | Description |
|---|---|
| `-flist FILE` | Text file listing input paths, one per line |
| `--files PATH [PATH ...]` | Input files or directories directly on the command line |
| `-o NAME` | Output prefix / project name (required) |
| `--name_map FILE` | Two-column file: col 1 = current sample name, col 2 = replacement name. Applies a deep rename throughout all output files and tables. |
| `-c {Yes,No}` | Re-run Amplicon Classifier on inputs (`Yes`/`No`) |
| `--ref GENOME` | Reference genome: `hg19`, `GRCh37`, `GRCh38`, `GRCh38_viral`, or `mm10` |

### AmpliconRepository upload options

| Flag | Description |
|---|---|
| `-u EMAIL` | AmpliconRepository username (email). If provided, triggers upload after aggregation. |
| `--upload_only {Yes,No}` | Skip aggregation and upload an existing `.tar.gz` directly |
| `-s {prod,dev}` | Target server (`prod` for most users) |

## Examples

**Aggregate a set of results:**
```bash
python src/AmpliconSuiteAggregator.py -flist input_list.txt -o MyProject
```

**Aggregate and upload to AmpliconRepository:**
```bash
python src/AmpliconSuiteAggregator.py -flist input_list.txt -o MyProject -u you@email.com -s prod
```

**Upload an already-aggregated file without re-aggregating:**
```bash
python src/AmpliconSuiteAggregator.py --files MyProject.tar.gz -o MyProject -u you@email.com --upload_only Yes -s prod
```

## Authors
- [Jens Luebeck](https://github.com/jluebeck) *(main contact)*
- Thorin Tabor
- Edwin Huang

## Issues
Bug reports and feature requests: [GitHub Issues](https://github.com/AmpliconSuite/AmpliconSuiteAggregator/issues)
