4. Support & FAQ

Support is provided at the GitHub issues page, the GitHub discussions, Discord or by email.

For support requests it is usually helpful if you provide details about your data (size and type of sequences) and your execution environment (CPU cores, RAM, operating system).

Community feedback and feature requests are also appreciated.

1. How to optimize performance

   Substantial gains in performance can be achieved by configuring the tool according to the needs of a given application instead of simply running it with with default settings. Some points to consider:

   • Set the block size (-b) and index chunks (-c) parameters according to the available resources on your system. Larger block sizes than default can substantially improve performance, e.g. using -b12 for the --fast mode or -b2 for the --very-sensitive mode. Returns are diminishing however and too large block sizes are not recommended.

   • Use a RAM drive for temporary files, e.g. -t /dev/shm on Linux.

   • Set the -e parameter (maximum expected value) as low as possible.

   • Set the -k parameter (number of target sequences to report alignments for) as low as possible. This will improve performance and reduce the use of temporary disk space and the size of the output files.

   • Configure the tabular output format to only report the output fields that are actually required (see output options).

   • Use the BLAST tabular format for machine-based processing of the output. Use the XML and SAM format only if required by your downstream tools or if you prefer it as a human-readable format.

   • Use the option --compress 1 to automatically generate gzip-compressed output files.

2. How to run the program on multiple input files?

   It is not recommended to run more than one instance of DIAMOND simultaneously on the same machine, because it is more efficient if you allocate more ressources to a single task by increasing the block size parameter -b and using lower numbers for -c. For this reason, input files should be processed consecutively. Pipes can also be used to process multiple input files. For example, this command will build a database from all fasta.gz files in the current directory:

   zcat *.fasta.gz | diamond makedb -d diamond_db
   

3. The program runs for a very long time and the output file remains empty.

   This is normal. Larger databases are split into chunks and the output is kept in temporary files at first and only merged in the end.

4. There are no temporary files.

   The temporary files are not visible using standard shell commands because unlink is invoked on them after creation, which ensures that the files will be removed in case of ungraceful termination of the program.

5. More than one alignment is reported for a single query and subject sequence.

   Due to the definition of HSPs, which are pairs of segments that form a linear alignment, any number of these may be contained in a single query/subject pair. Prior to version 2.0.0, the program reported additional HSPs found in the same query/subject pair. This behaviour can be changed using the --max-hsps option. Note that the default behaviour has changed since version 2.0.0.

6. The program does not appear to be sensitive enough / it does not find an alignment I expect it to find or that another aligner reported.

   There are a number of reasons that can cause hits to not be found or reported. In particular, even identical self-alignments of protein sequences may not be reported for some of the reasons listed below.

   1. The hit may not be deemed significant, i.e. its e-value is above the configured cutoff. This is possible even for short 100% identity matches. Also note that e-value computations are not compatible for different aligners most of the time.

   2. Repeat masking and compositional bias correction may cause hits to be filtered. This is usually desirable as these methods are highly effective in eliminating false positives. Repeat masking can be disabled using --masking 0 if required.

   3. There are limitations in aligning very short sequences of length <20, and this task requires some tuning of parameters.

   4. Seeds that occur too frequently in the input are ignored, which may cause problems if your data is extremely repetitive. This behaviour can be adjusted using the --freq-sd option.

   5. The program may not be sensitive enough for your application. You should try the more sensitive modes (options --sensitive up to --ultra-sensitive). Still, perfect results cannot be guaranteed by heuristical algorithms, but only by a rigorous Smith-Waterman computation.

7. The program terminates with an unclear or no error message.

   The task may have been killed by the system for running out of memory. Use dmesg to check for a respective kernel message. See instructions on memory usage. If you run the program on a cluster, you may need to allocate more memory to the task.

8. Are results consistent for multiple calls of the program?

   The program has a basic consistency guarantee that the same version run on the same input with the same parameters will produce identical results, regardless of the hardware, operating system, compiler, or number of CPU threads. If this was not the case, I would consider it a bug. You can check if results are according to the expected defaults on your system running the CTest unit tests.

   Beyond that, no guarantees of consistency can be made. DIAMOND like all fast aligners uses numerous heuristics that can affect results in unexpected ways.