Getting help

Greg Caporaso edited this page Jul 13, 2016 · 6 revisions

Table of contents

This page documents how to get help with QIIME 1. QIIME 2 is currently available as an early experimental (alpha) release. If you're looking for help with QIIME 2, you should start at

Useful resources

The following resources may be helpful when learning and using QIIME.

QIIME resources

To print configuration and version info for QIIME and its dependencies, run:

Educational resources

Scientific computing resources

Related projects

Learning QIIME

To get started with learning QIIME, you should begin with the QIIME tutorials.

Once you've worked through the Getting Started tutorials, you can begin to branch out to some of the additional functionality. You can browse the available QIIME scripts in the QIIME script index, which provides links to their help text. Most of the QIIME scripts contain usage examples that are based on real data. To try these usage examples, you can download the files from the corresponding directory in qiime_test_data. These files can also serve as examples of what your input files should look like. The same help text that is linked from the QIIME script index is also available by calling a QIIME script with the -h option (for example -h).

QIIME workshops offer the opportunity to learn from the QIIME developers in person, and typically cover QIIME and microbial community analysis, and provide an opportunity to gain hands-on experience with QIIME. Attending a QIIME workshop or hosting an official QIIME workshop at your location are excellent opportunities to get started with QIIME. See the QIIME workshop page for details.

Getting help with QIIME

The QIIME Forum is your primary resource for getting help with QIIME. Going to the QIIME Forum for help is much more efficient than contacting developers directly, as we have a large team of QIIME developers who regularly monitor the forum. We try to respond to questions posted on the QIIME Forum within one work day. On the other hand, if you email a QIIME developer directly, it may take days or weeks to get a response. Additionally, providing technical support for QIIME in a public forum allows us to reduce our support burden because other users can learn from our answers to your questions. This allows the developers to focus more time on improving QIIME and on our own research projects.

Before posting a question on the QIIME Forum, you should begin by searching to see if your question has already been answered. A good way to do this is to post an error message that you received in the search box.

If you can't find an answer to your question, you should post a new question. Taking the following steps when asking a question on the QIIME forum will help you to get the quickest response.

Step 1

Most importantly, you should create a small test data set that reproduces the error that you're getting, and send that data to us along with the exact command that is generating the error. This allows us to attempt to reproduce the error on our end, which makes it much faster to sort out what's going on than going back-and-forth with questions by e-mail.

For example, if you're trying to align 100,000 sequences with, and getting a failure, try to reduce that data set down to the smallest number of sequences that will reproduce that error, and send that fasta file. To do this, copy the fasta file (don't modify your original) and start extracting sequences from the file. Re-run the command that failed on the smaller input file(s), and then send us the smallest file that recreates the error you were seeing with the full file.

For example, try extracting the first sequence and see if you get the error. From the command line, call:

head -n 2 seqs.fasta > first_seq.fasta

to extract the first sequence (assuming that your fasta file is using the one-line-per-sequence format). If this gives the error, then sends us the first_seq.fasta file. If not, try increasing the number of sequences in that file, or try only running the last sequence in the file using tail instead of head.

Be sure to send all of the files necessary to generate the error, and any files that are getting created in failed run. If this is a workflow script, be sure to include any parameters file that you are using. The best thing to do is create a directory (e.g., align_seqs_failure_<your_name>) which contains all of the input files, run the command in that directory, save the command and output in a notes.txt file in that directory, zip it up, and send it with the command and output also in the e-mail.

For tips on how to send us files, see the note on 'Sending files to the QIIME developers' below.

Step 2

Once you've reduced to the smallest set of sequences that recreate the error, send us the exact command that you ran and the full error message that is being generated. Cut and paste this from the terminal.

Step 3

Run: -tf

in the terminal, and paste all of the text that is printed into the e-mail to us. This gives us information on what version of QIIME and its dependencies you are using.

If this seems like a lot of work to do before sending us a message, remember that we will end up asking you for it anyway at some point. By not having to wait for us to bounce questions back to you, you get your answer faster, and putting it together will help you improve your skills at debugging command line application issues. We find that in a lot of cases, running through step 1 above allows the user to figure out what the problem is on their own (e.g., this process would quickly let you figure out if a file ending with .fasta was not really a fasta file).

Sending files to the QIIME developers Dropbox (OS X/Windows/Linux) is a convenient (and free!) tool for sharing small data sets. See their help on publicly sharing files. This will allow you to publicly share a zip file, for example.

Reporting bugs and requesting new features

If you think you've identified a bug in QIIME, you should post it to the QIIME issue tracker. If there is a feature that you're interested in seeing a future version of QIIME, the QIIME issue tracker is also the place to post that.