Trinity: Frequently Asked Questions and Topics

Ideally, you will have access to a large-memory server, ideally having ~1G of RAM per 1M reads to be assembled (but often, much less memory may be required). We regularly run Trinity on our Dell 256G RAM 22-core server.

It depends on a number of factors including the number of reads to be assembled and the complexity of the transcript graphs. The assembly from start to finish can take anywhere from ~1/2 hour to 1 hour per million reads (your mileage may vary).

To troubleshoot individual graphs using Butterfly, see Advanced Guide to Trinity.

The initial Inchworm and Chrysalis steps need to be run on a single server as a single process, however parts of Chrysalis and all of Butterfly can be run as naive parallel processes on a computing grid.

Running Trinity.pl with the option: --no_run_quantifygraph will stop Trinity just before the parallel processes can be executed. There will be two sets of files generated, each containing commands that should be executed on a computing grid.

The first set of commands correspond t the Chrysalis quantifyGraph step, found at

after executing these commands on your computing grid, and ensuring that each succeeded, you can then execute the Butterfly commands found at:

(be sure to use the .adj extension, since this file includes other butterfly parameters passed through the Trinity.pl wrapper).

How to get each of these commands to run on your grid will depend on your computing infrastructure. We have several ways to do this via LSF, but they’re all home-grown solutions and not described here.

Once all butterfly commands have been executed, you can retrieve all the resulting assembled transcripts by concatenating the individual result files together like so:

Currently, the mappings of reads to transcripts are not reported. To obtain this information, we recommend realigning the reads to the assembled transcripts using Bowtie or BWA. A wrapper around Bowtie that will generate alignments for you is included in the Trinity package as:

and example data and example execution of this is included at:

for paired or single read data. See the various run.sh scripts available for examples.

If you have RNA-Seq data from multiple libraries and you want to run them all through Trinity in a single pass, simply combine all your left.fq files into one left.fq file, and combine all right.fq files into one right.fq file. Then run Trinity using these separately concatenated left and right input files.

If you have additional singletons, add them to the .fq file that they correspond to based on the sequencing method used (if they’re equivalent to the left.fq entries, add them there, etc).

There is no good way to combine strand-specific data with non-strand-specific data, unless you decide to treat the entire data set as non-strand-specific.

In nearly every case examined thus far, this is because the stacksize memory grew beyond its maximal setting. Chrysalis can sometimes recurse fairly deeply, in which case the stacksize can grow substantially. Before running Trinity, be sure that your stacksize is set to unlimited. On CentOS linux, you can check your default settings like so (it may be different on your linux distro):

and you would set the stacksize (and other settings) to unlimited like so:

and verify the new settings:

On Solaris, Ubuntu linux, and perhaps Mac OSX, the syntax is different, and might be:

On Ubuntu, type: ulimit -a to examine and verify your settings.

On snow leopard, you cannot set it to unlimited for some reason (older versions you could), so try to max it out.

If one or more QuantifyGraph (of Chrysalis) jobs should fail like so:

it is because these processes ran out of available memory. The fix is the following:

Occassionally (very rarely, such as one component per tens of thousands, if at all) Butterfly will encounter a complicated transcript graph and seems to take an eternity to process it. You will notice this by running top and seeing a java process that has been running for a very long time. For example, I’m running a dozen butterfly commands on my large server (22 cores, 256 GB RAM) and I can see various butterfly jobs running as java in the view:

A way to see exactly what jobs are running is to execute the following:

Most of the butterfly commands have been running for only a short period of time (seconds), but there are a couple that have been running for several minutes. Most commands will take less than a few minutes to run, and some can take up to an hour. If you see a butterfly command (java) that has been running for many hours, you can consider killing it and trying it again later with altered butterfly parameters. There are a couple of ways to kill the process.

From the command line, you can kill it like so:

where $pid is the process ID in the first column of the top output or second column of the ps output.

From within top, you can kill it by typing k, enter, $pid, enter. (on linux, this is how it works; your system may vary).

Once a Butterfly command has finished (or you’ve killed it to retry it later), the next butterfly command in the queue will take its place.

If all Butterfly commands complete successfully, then the Trinity.pl wrapper script will report success and concatenate all the individual butterfly assembly outputs into a single file (Trinity.fasta).

If any commands did not succeed, then the failed (or killed) commands will be reported and written to a file so that you can adjust the parameters and rerun. There are two primary reasons for why a Butterfly command might run forever:

Once all butterfly commands have been executed, you can retrieve all the resulting assembled transcripts by concatenating the individual result files together like so:

When butterfly commands fail, it’s usually due to not enough heap memory being available. This tends happen with the largest component (comp0). Failed butterfly commands will be written to a failed_cmds.txt file and the Trinity process will terminate. Try rerunning the failed commands (which should be very few, such as 1-3 out of the tens of thousands of commands) manually and resetting the heap size -Xmx value to a higher number, such as 20G. After these failed processes complete successfully, you can combine all the Butterfly results into a single file like so:

and consider the entire run a success (albeit with a little hand-holding).

There are a couple reasons why this error message might creep up.

Although Inchworm has the capability of running independently with different k-mer sizes up to 32 (the 64-bit limit with 2-bit base encoding), Chrysalis and Butterfly are current fixed at the 25mer k-mer size. In testing, we discovered early on that 25-mers appeared to be near-optimal across a different transcriptomes and different read abundance levels, and so fixed the value accordingly as part of the Trinity process. Future development will aim to expose the k-mer setting as an option.

You can do so, but you wouldn’t be able to benefit as from the strand-specificity, since you’ll need to run Trinity in non-strand-specific mode.

The transcript names found in the output FASTA file are named like:

This is a product of graphing algorithms used to generate them, which is explained in detail in the Advanced Guide to Trinity.

In short, X defines the graphical component generated by Chrysalis (from clustering inchworm contigs). Butterfly might tease subgraphs apart from each other within a single component, based on the read support data. This gives rise to subgraphs (cY). Each subgraph then gives rise to path sequences (seqZ).

While isoforms should have the same component number, transcripts sharing the same component number aren’t always isoforms. Those sequences with the same component number are derived from the same isolated de Bruijn graph.