galantelab/fredy repository overview

Fredy is a user-friendly pipeline designed to identify, quantify, and analyze chimeric transcripts from RNA-Seq data. The pipeline utilizes well-established tools such as StringTie2 for transcriptome assembly and quantification. In addition, machine learning algorithms provided by RNASamba are used to predict whether a transcript is coding. To further enhance the analysis, Fredy also incorporates HMMER and Python3 scripts to compare protein domains and identify potential alterations. With these tools, Fredy provides a comprehensive approach to chimeric transcript analysis that is both efficient and effective.

⁠Installation

⁠Manual installation

The source code for FREDY can be obtained in our github page using the following command:

git clone https://github.com/galantelab/fredy.git

Inside FREDY’s directory, build a docker image:

cd fredy
sudo docker build -f Dockerfile -t fredy .

⁠Pulling image

You can acquire a built docker image from Docker Hub⁠ registry:

sudo docker pull galantelab/fredy

⁠Databases

We provide all the necessary databases to run FREDY, catering to human functionality. In our comprehensive documentation available in the supplementary material, we offer a s tep-by-step guide to generating these exact files for other species.

To use star_index.tar.gz you should uncompress the folder:

tar -xvf star_index.tar.gz

⁠Usage

FREDY has seven subcommands: “star”, “string”, “chimeric”, “coding”, “pfam”, “expression” and “results”.

fredy [subcommand] <options>

Subcommands may be invoked by the help menu:

fredy help

⁠Commands and options

⁠Star

The first step in the FREDY’s pipeline is the “star”. The inputs to this command are FASTQ files and a STAR index (pre-made available here⁠). The output is a sorted and filtered BAM aligned file, which will become the input to the next step. This command supports all types of RNA-Seq data (paired-end, single-end and long-reads), either compressed (as .gz) or not.

OPTIONS:

Example

docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v <star_index-path>:/home/fredy/star_index/ -v <fastq-path>:/home/fredy/input/ -v <output-path>:/home/fredy/output/ fredy star -o test -i /home/fredy/star_index/ -f /home/fredy/input/<fastq-path>

Where:

<star_index-path> is the directory where star_index was downloaded. Ex.: $PWD/star_index/

<fastq-file-path> is the directory where all FASTQ files are. Ex.: if $PWD/*.fastq.gz type $PWD/

<output-path> is the output directory. Ex.: $PWD/output/

<fastq-path> is a .txt file inside /home/fredy/input/ with the docker path (for instance /home/fredy/input/test.fastq.gz) to the FASTQ files.

⁠String

The next step in the pipeline is “string”. This subcommand performs a transcriptome assembly with the BAMs generated in the previous step (or custom BAMs provided by the user). The output of this analysis is a GTF file representing the transcriptome from all samples.

OPTIONS:

Example

docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v <gtf-file-path>:/home/fredy/gtf/ -v <output-path>:/home/fredy/output/ fredy string -o test -a /home/fredy/gtf/<gtf-file>`

Where:

<gtf-file-path> is the directory where gtf was downloaded. Ex.: if $PWD/gencodev36.annotation.gtf type $PWD/

<output-path> is the output directory. Ex.: $PWD/output/

<gtf-file> is a GTF inside /home/fredy/gtf/. Ex.: /home/fredy/gtf/gencodev36.annotation.gtf

⁠Chimeric

In the “chimeric” step, the pipeline identifies novel transcripts based on the GTF file generated from the “string” subcommand. Here, FREDY uses a list of events provided by the user to find transcripts containing overlaps between exons and the given events. Again, a GTF file and also a FASTA file with all transcripts found are the outputs provided.

⁠

OPTIONS:

Example

docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v <gtf-file-path>:/home/fredy/gtf/ -v <genome-file-path>:/home/fredy/ref_fa/ -v <events-file-path>:/home/fredy/events/ -v <output-path>:/home/fredy/output/ fredy chimeric -o test -g /home/fredy/gtf/<gtf-file> -G /home/fredy/ref_fa/<genome-file> -i /home/fredy/events/<event-file>

Where:

<gtf-file-path> is the directory where GTF file was downloaded. Ex.: if $PWD/gencodev36.annotation.gtf type $PWD/

<genome-file-path> is the directory where the reference genome and reference genome index were downloaded. Ex.: if $PWD/hg38.fa type $PWD/

<events-file-path> is the directory where the events are. Ex.: if $PWD/events.bed type $PWD/

<output-path> is the output directory. Ex.: $PWD/output/

<gtf-file> is a GTF file inside /home/fredy/gtf/. Ex.: /home/fredy/gtf/gencodev36.annotation.gtf

<genome-file> is a .fa inside /home/fredy/ref_fa/. Ex.: /home/fredy/ref_fa/hg38.fa

<events-file> is a .bed inside /home/fredy/events/. Ex.: /home/fredy/events/events.bed

⁠Coding

The “coding” subcommand classifies the novel transcripts identified in the “chimeric” step as coding or non-coding. Here, FREDY uses a model trained by RNASamba (available at here⁠) to calculate the probability of a transcript being coding. In the end, a FASTA file with the protein sequences of all coding transcripts considered by our criteria is created.

OPTIONS:

Example

docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v <rnasambamodel-file-path>:/home/fredy/rnasamba/ -v <proteinseq-file-path>:/home/fredy/proteinseq/ -v <output-path>:/home/fredy/output/ fredy coding -o test -m /home/fredy/rnasamba/<rnasambamodel-file> -d /home/fredy/proteinseq/<proteinseq-file>

Where:

<rnasambamodel-file-path> is the directory where RNASamba model was downloaded. Ex.: if $PWD/model.hdf5 type $PWD/

<proteinseq-file-path> is the directory where the protein sequences file was downloaded. Ex.: if $PWD/hg38.pep.fa type $PWD/

<output-path> is the output directory. Ex.: $PWD/output/

<rnasambamodel-file> is a .hdf5 inside /home/fredy/rnasamba/. Ex.: /home/fredy/rnasamba/model.hdf5

<proteinseq-file> is a .fa inside /home/fredy/proteinseq/. Ex.: /home/fredy/proteinseq/hg38.pep.fa

⁠Pfam

The “pfam” step searches for protein domains in the novel transcripts that passed the user’s predefined coding probability and subsequently compares them with the host’s protein domains. In order to identify them, we use HMMER trained with the PFAM database. The output of this subcommand is a TSV file comparing the protein domains of the novel transcripts identified with those of the host genes.

OPTIONS:

Example

docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v <pfammodel-file-path>:/home/fredy/pfammodel/ -v <output-path>:/home/fredy/output/ fredy pfam -o test -M <pfammodel-file>

Where:

<pfammodel-file-path> is the directory where PFAM model was downloaded. Ex.: if $PWD/Pfam-A.hmm type $PWD/

<output-path> is the output directory. Ex.: $PWD/output/

<pfammodel-file> is a .hmm inside /home/fredy/pfammodel/. Ex.: /home/fredy/pfammodel/Pfam-A.hmm

⁠Expression

The FREDY's “expression” subcommand quantifies all the transcriptomes assembled by the StringTie2's “expression” function. The expression results, in TPM (transcript per million) per transcript per sample, are made available as a TSV file.

OPTIONS:

Example

docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v <output-path>:/home/fredy/output/ fredy expression -o test

Where:

<output-path> is the output directory. Ex.: $PWD/output/

⁠Results

Finally, the “results” subcommand compiles all relevant information from the previous steps. Moreover, if the novel transcripts contribute to the expression of their respective host genes, this step further generates boxplots to show the relative contribution of such expression patterns.

OPTIONS:

Example

docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v <output-path>:/home/fredy/output/ fredy results -o test

Where:

<output-path> is the output directory. Ex.: $PWD/output/

⁠Practical workflow

In order to execute FREDY, we selected RNA-seq paired-end data of 2 samples related to the cell line K562 from the ENCODE Project⁠.

First, you should download the data:

mkdir fastq

cd fastq/

##ENCLB063ZZZ R1
wget https://www.encodeproject.org/files/ENCFF001RWF/@@download/ENCFF001RWF.fastq.gz
mv ENCFF001RWF.fastq.gz ENCLB063ZZZ_R1.fastq.gz

##ENCLB063ZZZ R2
wget https://www.encodeproject.org/files/ENCFF001RWC/@@download/ENCFF001RWC.fastq.gz
mv ENCFF001RWC.fastq.gz ENCLB063ZZZ_R2.fastq.gz

##ENCLB059ZZZ R1
wget https://www.encodeproject.org/files/ENCFF001RDE/@@download/ENCFF001RDE.fastq.gz
mv ENCFF001RDE.fastq.gz ENCLB059ZZZ_R1.fastq.gz

##ENCLB059ZZZ R2
wget https://www.encodeproject.org/files/ENCFF001RCW/@@download/ENCFF001RCW.fastq.gz
mv ENCFF001RCW.fastq.gz ENCLB059ZZZ_R2.fastq.gz

cd ..

And download the databases of FREDY:

mkdir db
cd db/

## STAR Index (Based on Human hg38 - Gencode v36)
wget https://bioinfohsl-tools.s3.amazonaws.com/fredy/databases/star_index.tar.gz
tar -xvf star_index.tar.gz

## Gencode v36 as the human annotation
wget https://bioinfohsl-tools.s3.amazonaws.com/fredy/databases/gencode.v36.annotation.gtf

## hg38 as the human reference genome
wget https://bioinfohsl-tools.s3.amazonaws.com/fredy/databases/hg38.fa

## Aminoacid sequence
wget https://bioinfohsl-tools.s3.amazonaws.com/fredy/databases/hg38.pep.fa

## RNASamba model
wget https://bioinfohsl-tools.s3.amazonaws.com/fredy/databases/human38_model.hdf5

## HMMer model
wget https://bioinfohsl-tools.s3.amazonaws.com/fredy/databases/Pfam-A.hmm
wget https://bioinfohsl-tools.s3.amazonaws.com/fredy/databases/Pfam-A.hmm.h3f
wget https://bioinfohsl-tools.s3.amazonaws.com/fredy/databases/Pfam-A.hmm.h3i
wget https://bioinfohsl-tools.s3.amazonaws.com/fredy/databases/Pfam-A.hmm.h3m
wget https://bioinfohsl-tools.s3.amazonaws.com/fredy/databases/Pfam-A.hmm.h3p

## Retrocopies events
wget https://bioinfohsl-tools.s3.amazonaws.com/rcpedia/downloads/beds/RCP_9606.bed
cut -f 1,2,3,5 RCP_9606.bed | sort -k1,1 -k2,2n > RCP_9606.bed4

cd ..

Then, prepare a file with the FASTQ PATHs:

ls fastq/*fastq.gz | awk '{print "/home/fredy/"$1}' > files.txt

After that, install and build a docker image:

git clone https://github.com/galantelab/fredy.git
cd fredy
sudo docker build -f Dockerfile -t fredy .
cd ..

Finally, you will be able to execute fredy as follows:

• “star” step:

time docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v $PWD:/home/fredy fredy star -o /home/fredy/K562 -i /home/fredy/db/star_index -f /home/fredy/files.txt

• “string” step:

time docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v $PWD:/home/fredy fredy string -o /home/fredy/K562 -a /home/fredy/db/gencode.v36.annotation.gtf

• “chimeric” step:

time docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v $PWD:/home/fredy fredy chimeric -o /home/fredy/K562 -a /home/fredy/db/gencode.v36.annotation.gtf -g /home/fredy/db/hg38.fa -e /home/fredy/db/RCP_9606.bed4

• “coding” step:

time docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v $PWD:/home/fredy fredy coding -o /home/fredy/K562 -m /home/fredy/db/human38_model.hdf5 -d /home/fredy/db/hg38.pep.fa

• “pfam” step:

time docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v $PWD:/home/fredy fredy pfam -o /home/fredy/K562 -M /home/fredy/db/Pfam-A.hmm

• “expression” step:

time docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v $PWD:/home/fredy fredy expression -o /home/fredy/K562

• “results” step:

time docker run --rm -u $(id -u):$(id -g) -w $(pwd) -v $PWD:/home/fredy fredy results -o /home/fredy/K562

All information related to the chimeric transcripts identified by FREDY are available in the final output named “results.tsv”. If you wish to inspect these transcripts in a Genome Browser such as at UCSC⁠ you can easily upload the “K562/chimeric/chimeric.gtf” file, also provided by the FREDY’s pipeline, to the “custom tracks”.

⁠Contact

Rafael Luiz Vieira Mercuri - ([email protected]⁠)

Thiago Luiz Araújo Miller - ([email protected]⁠)

Pedro Alexandre Favoretto Galante - ([email protected]⁠)

Project Link: https://github.com/galantelab/fredy⁠

⁠Authors

Rafael Luiz Vieira Mercuri

Thiago Luiz Araújo Miller

Filipe Ferreira dos Santos

Matheus de Lima

Aline Rangel-Pozzo

Pedro Alexandre Favoretto Galante