Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update readme #208

Merged
merged 1 commit into from
Jan 12, 2018
Merged

update readme #208

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 95 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,37 +1,81 @@
ARIBA
=====
# ARIBA

Antimicrobial Resistance Identification By Assembly

For methods and benchmarking, please see the [preprint on biorxiv][ariba biorxiv].
For how to use ARIBA, please see the [ARIBA wiki page][ARIBA wiki].

[![Build Status](https://travis-ci.org/sanger-pathogens/ariba.svg?branch=master)](https://travis-ci.org/sanger-pathogens/ariba)
[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-brightgreen.svg)](https://github.com/ssjunnebo/ariba/blob/master/LICENSE)
[![status](https://img.shields.io/badge/MGEN-10.1099%2Fmgen.0.000131-brightgreen.svg)](http://mgen.microbiologyresearch.org/content/journal/mgen/10.1099/mgen.0.000131)

For how to use ARIBA, please see the [ARIBA wiki page][ARIBA wiki].
## Contents
* [Introduction](#introduction)
* [Quick Start](#quick-start)
* [Installation](#installation)
* [Required dependencies](#required-dependencies)
* [Using pip3](#using-pip3)
* [From Source](#from-source)
* [Docker](#docker)
* [Debian (testing)](#debian-testing)
* [Ubuntu](#ubuntu)
* [Dependencies and environment variables](#dependencies-and-environment-variables)
* [Temporary files](#temporary-files)
* [Usage](#usage)
* [License](#license)
* [Feedback/Issues](#feedbackissues)
* [Citation](#citation)

## Introduction
ARIBA is a tool that identifies antibiotic resistance genes by running local assemblies.
It can also be used for [MLST calling](https://github.com/sanger-pathogens/ariba/wiki/MLST-calling-with-ARIBA).

The input is a FASTA file of reference sequences (can be a mix of genes and noncoding sequences) and paired sequencing reads. ARIBA reports which of the reference sequences were found, plus detailed information on the quality of the assemblies and any variants between the sequencing reads and the reference sequences.

## Quick Start
Get reference data, for instance from [CARD](https://card.mcmaster.ca/). See [getref](https://github.com/sanger-pathogens/ariba/wiki/Task%3A-getref) for a full list.

ariba getref card out.card

Prepare reference data for ARIBA:

ariba prepareref -f out.card.fa -m out.card.tsv out.card.prepareref

Run local assemblies and call variants:

ariba run out.card.prepareref reads1.fastq reads2.fastq out.run

Summarise data from several runs:

ariba summary out.summary out.run1/report1.tsv out.run2/report2.tsv out.run3/report3.tsv

Please read the [ARIBA wiki page][ARIBA wiki] for full usage instructions.

Installation
------------
## Installation

ARIBA has the following dependencies, which need to be installed:
If you encounter an issue when installing ARIBA please contact your local system administrator. If you encounter a bug please log it [here](https://github.com/sanger-pathogens/ariba/issues) or email us at [email protected].

### Required dependencies
* [Python3][python] version >= 3.3.2
* [Bowtie2][bowtie2] version >= 2.1.0
* [CD-HIT][cdhit] version >= 4.6
* [MUMmer][mummer] version >= 3.23

ARIBA also depends on several Python packages, all of which are available
via pip. Installing ARIBA with pip3 will get these automatically if they
are not already installed:
* dendropy >= 4.2.0
* matplotlib (no minimum version required, but only tested on 2.0.0)
* pyfastaq >= 3.12.0
* pysam >= 0.9.1
* pymummer >= 0.10.1

Once the dependencies are installed, install ARIBA using pip:
### Using pip3
Install ARIBA using pip:

pip3 install ariba

ARIBA also depends on several Python packages, all of which are available
via pip, so the above command will get those automatically if they
are not installed. The packages are dendropy >= 4.2.0, matplotlib (no
minimum version required, but only tested on 2.0.0),
pyfastaq >= 3.12.0, pysam >= 0.9.1, and pymummer >= 0.10.1.

Alternatively, you can download the latest release from this github repository,
or clone the repository. Then run the tests:
### From Source
Download the latest release from this github repository or clone it. Run the tests:

python3 setup.py test

Expand All @@ -40,11 +84,11 @@ If the tests all pass, install:
python3 setup.py install

### Docker
ARIBA can be run in a Docker container. First of all install Docker, then to install ARIBA run:
ARIBA can be run in a Docker container. First install Docker, then install ARIBA:

docker pull sangerpathogens/ariba

To use ARIBA you would use a command such as this (substituting in your directories), where your files are assumed to be stored in /home/ubuntu/data:
To use ARIBA use a command like this (substituting in your directories), where your files are assumed to be stored in /home/ubuntu/data:

docker run --rm -it -v /home/ubuntu/data:/data sangerpathogens/ariba ariba -h

Expand All @@ -54,9 +98,7 @@ ARIBA is available in the latest version of Debian, and over time will progressi

sudo apt-get install ariba


### Ubuntu

You can use `apt-get` (see above), or to ensure you get the latest version of ARIBA, the following commands can be
used to install ARIBA and its dependencies. This was tested on a new instance of Ubuntu 16.04.

Expand Down Expand Up @@ -90,11 +132,9 @@ Note that ARIBA also runs `bowtie2-build`, for which it uses the
it would try to use

$HOME/bowtie2-2.1.0/bowtie2-build


### Temporary files
## Temporary files


ARIBA can temporarily make a large number of files whilst running, which
are put in a temporary directory made by ARIBA. The total size of these
files is small, but there can be a many of them. This can be a
Expand Down Expand Up @@ -128,16 +168,44 @@ This forces the temporary directory to be placed in the output
directory, and temporary files are kept. It is intended for
debugging.

## Usage
usage: ariba <command> <options>

optional arguments:
-h, --help show this help message and exit

Available commands:

aln2meta Converts multi-aln fasta and SNPs to metadata
expandflag Expands flag column of report file
flag Translate the meaning of a flag
getref Download reference data
micplot Make violin/dot plots using MIC data
prepareref Prepare reference data for input to "run"
pubmlstget Download species from PubMLST and make db
pubmlstspecies
Get list of available species from PubMLST
refquery Get cluster or sequence info from prepareref output
run Run the local assembly pipeline
summary Summarise multiple reports made by "run"
test Run small built-in test dataset
version Get versions and exit

Please read the [ARIBA wiki page][ARIBA wiki] for full usage instructions.

Usage
-----
## License
ARIBA is free software, licensed under [GPLv3](https://github.com/sanger-pathogens/ariba/blob/master/LICENSE).

Please read the [ARIBA wiki page][ARIBA wiki] for usage instructions.
## Feedback/Issues
Please report any issues to the [issues page](https://github.com/sanger-pathogens/ariba/issues) or email [email protected]

## Citation
If you use this software please cite:

ARIBA: rapid antimicrobial resistance genotyping directly from sequencing reads
Hunt M, Mather AE, Sánchez-Busó L, Page AJ, Parkhill J , Keane JA, Harris SR.
Microbial Genomics 2017. doi: [110.1099/mgen.0.000131](http://mgen.microbiologyresearch.org/content/journal/mgen/10.1099/mgen.0.000131)

Build status: [![Build Status](https://travis-ci.org/sanger-pathogens/ariba.svg?branch=master)](https://travis-ci.org/sanger-pathogens/ariba)

[ariba biorxiv]: http://biorxiv.org/content/early/2017/04/07/118000
[bowtie2]: http://bowtie-bio.sourceforge.net/bowtie2/index.shtml
Expand Down