Software for Quantifying Interspersed Repeat Expression

Installation

SQuIRE Pipeline Overview

SQuIRE Pipeline Options

FAQs

Example Pipeline

Read about SQuIRE in:

Wan R Yang, Daniel Ardeljan, Clarissa N Pacyna, Lindsay M Payer, Kathleen H Burns; SQuIRE reveals locus-specific regulation of interspersed repeat expression, Nucleic Acids Research, , gky1301, https://doi.org/10.1093/nar/gky1301

Installation

SQuIRE is available on bioconda and can be installed using conda. We suggest running conda with mamba for speedup.

Conda is a package manager that installs and runs packages and their dependencies. Conda also creates virtual environments and allows users to switch between those environments. Mamba is a reimplementation of conda in C++ with faster dependency solving.

The instructions below install conda, mamba, and a conda virtual environment for SQuIRE.

1. Download Miniconda (a lightweight distribution of conda) from https://conda.io/miniconda.html

   • wget -c https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh
   • Documentation will appear as the software downloads

2. Run the Miniconda installer

   • bash Miniconda3-latest-Linux-x86_64.sh
   • Press ENTER key to review the Miniconda license
   • Type yes to approve the license terms
   • Pres ENTER key to confirm install locatino (or enter a preferred location)
   • Type yes to add Miniconda2 into your PATH

3. Restart shell

   • exec $SHELL

4. Configure conda channel priority

   • Add conda channels in the following order:

     conda config --add channels defaults 
     conda config --add channels bioconda
     conda config --add channels conda-forge

   • Confirm that the channels are listed in the following order by running cat $(dirname $CONDA_PREFIX)/.condarc:

     channels:
      - conda-forge
      - bioconda
      - defaults

     • Each channel has a higher priority than those listed below it. Conda will install packages from a higher priority channel over any version from a lower priority channel by default.
   • Check that channel priority is set to flexible with conda config --describe channel_priority
     • Channel priority should be set to flexible by default. If it is not, run conda config --set channel_priority flexible

5. Install mamba in the base environment

   • conda install mamba -n base -c conda-forge

6. Create a new environment and install SQuIRE!

   • mamba create -n squire -c bioconda squire
   • To begin using SQuIRE, activate the environment: conda activate squire

Many thanks to Rohini Gadde for setting up the SQuIRE Bioconda package!

Notes

*SQuIRE is compatible with the following specific versions of software:*

• STAR 2.5.3a
• bedtools 2.25.0
• samtools 1.1
• stringtie 1.3.3
• DESeq2 1.16.1
• R 3.4.1
• Python 2.7

If installing these software with conda is unsuccessful, we recommend installing these versions with squire Build to ensure compatibility with SQuIRE.

• squire Build:
  • squire Build -s all

Pipeline Overview

Preparation Stage 1) Fetch: Downloads input files from RefGene and generates STAR index Only needs to be done once initially to acquire genomic input files or if a new build is desired.

2) Clean: Filters Repeatmasker file for Repeats of interest, collapses overlapping repeats, and returns as BED file.

Optional: Incorporation of non-reference TE sequence

Quantification Stage

1) Map: Aligns RNAseq data

2) Count: Quantifies RNAseq reads aligning to TEs

Analysis Stage

1) Call: Compiles and outputs differential expression from multiple alignments

Follow-up Stage 1) Draw: Creates BEDgraphs from RNAseq data

2) Seek: Reports individual transposable element sequences

An example pipeline with sample scripts is described here.

Arguments for each step

squire Build

Use Build only if conda create does not successfully install software.

• Download and install required software (STAR, Bedtools, Samtools, and/or Stringtie)

• Adds software to PATH

• usage squire Build -o -s STAR,bedtools,samtools,stringtie -v

Preparation Stage

squire Fetch

• Downloads required files from repeatmasker

• Only needs to be used the first time SQuIRE is used to transfer required genomic build references to your machine

• Outputs annotation files, chromosome fasta file(s) and STAR index

• usage: squire Fetch [-h] -b <build> [-o <folder>] [-f] [-c] [-r] [-g] [-x] [-p <int>] [-k] [-v]

squire Clean

• Filters genomic coordinates of Repeats of interest from repeatmasker, collapses overlapping TEs, and returns BED file and count of subfamily copies.

• Only needs to be done at the first use of SQuIRE pipeline to clean up the index files

• Outputs .bed file of TE coordinates, strand and divergence

• usage: squire Clean [-h] [-r <rmsk.txt or file.out>] [-b <build>] [-o <folder>] [-c <classes>] [-f <subfamilies>] [-s <families>] [-e <file>] [-v]

Non-reference File Format

For known TE sequences that are not included in the reference genome, a tab-delimited file can be provided to SQuIRE to incorporate the non-reference TEs into the analysis. This file can be inputted into the Map and Clean steps with the --extra parameter.

The following information should be included in the file:

1. Chromosome or Plasmid Identification
   • SQuIRE will add an identifier with an underscore "_" and the insertion type to distinguish the annotation from the reference genome.
2. Insertion Start
   • 0-based numerical start location of the non-reference repeat.
3. Insertion End
   • 0-based numerical end location. For chromosome insertions, this will only be one base different from Insertion Start.
4. Strand
   • + or - Orientation of 'sense' strand of TE annotation.
5. TE classification
   • Provide TE Subfamily, Family and Order, separated by colons ":".
6. Insertion Type
   • Must be one of: polymorphic insertion, novel insertion, plasmid, or transgene.
7. Left-Flank Sequence
   • Flanking sequence before the TE insertion.
8. Right-Flank Sequence
   • Flanking sequence after the TE insertion.
9. TE Sequence
   • Non-reference TE sequence.

Example File

Quantification Stage

squire Map

• Aligns RNAseq reads to STAR index allowing for multiple alignments

• Outputs .bam file

• usage: squire Map [-h] [-1 <file_1.fastq or file_1.fastq.gz>] [-2 <file_2.fastq or file_2.fastq.gz>] [-o <folder>][-f <folder>] -r <int> [-n <str>] [-3 <int>] [-e <file.txt>] [-b <build>] [-p <int>] [-v]

-b ,--build , UCSC designation for genome build, eg. 'hg38' (required if more than 1 build in clean_folder) -3 , --trim3 | Trim bases from right end of each read before alignment. Optional; default = 0 -e , --extra | Filepath of text file containing non-reference repeat sequence and genome information. Optional, default = False -g , --gtf | Optional GTF of genome transcripts. For those interested in gene transcription -p , --pthreads | Launch parallel threads. Optional, default = '1' -v, --verbosity | Print messages and runtime records to stderr. Optional; default = False

squire Count

• Quantifies RNAseq reads aligning to TEs and genes
• Outputs counts for RefSeq genes and TEs at the locus and subfamily levels

• usage: squire Count [-h] [-m <folder>] [-c <folder>] [-o <folder>] [-t <folder>] [-f <folder>] -r <int> [-n <str>] [-b <build>] [-p <int>] [-s <int>] [-e EM] [-v]

Analysis Stage

squire Call

• Performs differential expression analysis on TEs and genes

• Outputs DEseq2 output and plots

• usage squire Call [-h] -1 <str1,str2> or <str> -2 <str1,str2> or <str> -A -B [-o ] [-s] [-p ] [-N ] [-f ] [-v]

  Arguments
  -h, --help	show this help message and exit
  -1 <str1,str2> or <str>, --group1 <str1,str2> or <str>	List of basenames for group1 (Treatment) samples, can also provide string pattern common to all group1 basenames
  -2 <str1,str2> or <str>, --group2 <str1,str2> or <str>	List of basenames for group2 (Control) samples, can also provide string pattern common to all group2 basenames
  -A , --condition1	Name of condition for group1
  -B , --condition2	Name of condition for group2
  -o , --call_folder	Destination folder for output files (optional; default='squire_call')
  -s, --subfamily	Compare TE counts by subfamily. Otherwise, compares TEs at locus level (optional; default=False)
  -p , --pthreads	Launch parallel threads(optional; default='1')
  -N , --projectname	Basename for project
  -f , --output_format	Output figures as html or pdf
  -v, --verbosity	Want messages and runtime printed to stderr (optional; default=False)

Follow-up Stage

squire Draw

• Creates bedgraphs and bigwigs from RNAseq data

• usage squire Draw [-h] [-f ] [-m ] [-o ] [-n ] [-s ] -b [-l] [-p ] [-v]

squire Seek

• Retrieves transposable element sequences from chromosome fasta files

• Outputs sequences in FASTA format

• usage squire Seek [-h] -i -o -g [-v]

FAQs

How do I know if my data is stranded or not?

The RNA-seqlopedia by Cresko Lab at University of Oregon outlines strand specific data in section 3.7 Preparation of stranded libraries. You can verify the strand specificity with the researcher who collected the data, or use an outside program like infer-experiment.py in RSeQC or the libtype option in Salmon.

How much memory does each step require?

You can gauge how much vmem to assign to each job based on the number of reads in your datasets.

Can SQuIRE be used on ChIP or small RNA?

SQuIRE has not yet been tested with ChIP or small RNA sequencing data, so its compatibility has not yet been determined.

Example Pipeline

INSTRUCTIONS

1. Copy the sample_scripts folder to your project folder

   • mkdir <project folder>/scripts
   • cp SQuIRE/sample_scripts/* <project folder>/scripts
   • cd <project folder>/scripts

2. Fill out the arguments.sh file

3. Replace "squire@email.com" in the #$ -M squire@email.com line with your email address to get alert of script completion and memory usage

4. Submit jobs to SGE cluster (the -cwd option results in error and output files associated to stay in your current working directory)

   • qsub -cwd fetch.sh arguments.sh
   • qsub -cwd clean.sh arguments.sh
   • qsub -cwd loop_map.sh arguments.sh
   • qsub -cwd loop_count.sh arguments.sh
   • qsub -cwd call.sh arguments.sh
   • qsub -cwd loop_draw.sh arguments.sh

5. If a memory or segmentation fault error occurs, edit the #$ -l mem_free and #$ -l h_vmem lines to increase memory usage for the appropriate script.