Steps for most efficiently getting help with QIIME

[Greg Caporaso]

There are a few steps you can take when asking a question on the QIIME forum to help get the quickest response.

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 align_seqs.py, 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 (so you don't mess with your original) and start extracting sequences from the file and re-testing. Try extracting the first sequence and see if you get an 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'. If you're using a template alignment (e.g. with PyNAST), do the same thing there: reduce to the smallest number of sequences that will recreate the error.

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 the parameters file that you are using. The best thing to do is create a directory (e.g., align_seqs_failure_<my_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.


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.

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


3. Run:

print_qiime_config.py -t

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., a file ending with '.fasta' is not really a fasta file). Finally, the less time that we spend on support, the more time we can spend on new features in QIIME and our own research.


Sending files to the QIIME developers
Some convenient (and free!) tools for sharing small data sets are Dropbox (OS X/Windows/Linux) and CloudAPP (OS X only). These will allow you to publicly share a zip file, for example.  

[Greg Caporaso]

Here's an interesting article on this topic that just came out in PLoS Computational Biology:

http://www.ploscompbiol.org/article/info:doi%2F10.1371%2Fjournal.pcbi.1002202

[Greg Caporaso]

This documentation has now been ported to http://help.qiime.org. Some more recent content has been added there.