23 June 2017, TERIUS version 1.0

##########################################################################
# This is a TERIUS user guide explaining the TERIUS workflow. 
#
# The example commands shown here are based on test data and annotations given with the source code.
#
# If you wish to follow the example commands, please run all commands in the scripts directory or add directory information to the commands. 
#
# TERIUS takes annotation files in refFlat format, with additional column of transcript ID added to GenePred format (https://genome.ucsc.edu/FAQ/FAQformat.html#format9)
#
# Thus refFlat format consists of: gene_name, transcript_id, chromosome, strand, txStart, txEnd, cdsStart, cdsEnd, exonCount, exonStarts, exonEnds. 
#
# Please note that all "starts" (txStart, cdsStart, exonStarts) are 0-based in refFlat and GenePred format.
# Please note that all transcript_ids in refFlat file should be unique.
##########################################################################

*** Requirements 
TERIUS is a Python-based script. It runs on Linux CentOS 6.0 and it requires following programs;

samtools (version 0.1.19-44428cd, must be in the PATH)
Python (version 2.6.9
rpy (version 1.0.3)
R (version 2.15.1)
numpy (version 1.9.2)
	

(1) Writing Datasets.py file

---------- used script:

write_datasets.py

Usage: python <scripts_directory>write_datasets.py -d <scripts_directory>Datasets.py -b <input_bam> -n <nickname_for_bam> -s <strandSpecific/nonstrandSpecific> -e <se/pe> -l <first/second/fr-first/fr-second>

This script creates Bam function in Datasets.py that contains informations about bam files. The script also enables the users to use short 'nicknames' for bam files rather than its full, original name. 
This step is required for all bam files that the user intends to use in downstream TERIUS.

---------- example: 
 
python write_datasets.py -d Datasets.py -b ../dataset/BAM/RPS/HeLa_RIBO_chr22s.bam -n HeLa_Ribobam -s strandSpecific -e se -l second 

python write_datasets.py -d Datasets.py -b ../dataset/BAM/UAS/CLIP/HeLa_UPF1_chr22s.bam -n HeLa_UPF1bam -s strandSpecific -e se -l second

python write_datasets.py -d Datasets.py -b ../dataset/BAM/UAS/RNA/HeLa_RNA_chr22s.bam -n HeLa_RNAbam -s nonstrandSpecific -e se -l second

---------- arguments:

-d		Datasets.py file in scripts directory
-b		input bam with full path
-n		nickname for the input bam file designated by users
-s 		strandSpecific if the input bam is stranded; nonstrandSpecific if not
-e		se if library is single-end; pe if library is paired-end
-l		second/first if library is single-end and secondstrand/firststrand; fr-first/fr-second if library is paired-end and forward-reverse firststrand/secondstrand

----------- output files:

Datasets.py 		file with bam file information added inside its Bam function


2) Ribosome periodicity score (RPS)

----------- used script:

TERIUS_part1.py 

Usage: python <scripts_dir>TERIUS_part1.py -l <cell_line> -r <refFlat> -s <scripts_dir>  -o <output_dir> -t <RPS_cutoff> -c <coding_gene_prior> -n <noncoding_gene_prior> -b <bam_nickname> -f <RPS_model_prefix>

This step calculates weighted relative entropy and ribosome periodicity score (RPS) to separate coding and non-coding transcripts.
RPS outputs posterior probabilty of transcripts.
For example, if RPS score for a transcript B is 0.6, it means that the probability of this transcript being non-coding is 0.6.

---------- example:

python TERIUS_part1.py -l HeLa -r ../dataset/test_anno/hg19_PCG_lncRNA.refFlat -s ./ -o ../results_new/ -t 0.4 -c 0.55 -n 0.45 -b HeLa_Ribobam -f ../dataset/models/RPS_meanModel_

---------- arguments:

-l		cell line used to generate Ribo-seq library
-r		input refFlat
-s		scripts directory
-o		output directory
-t		posterior probability cutoff for RPS, a number between 0 and 1, default is 0.5
-c 		prior probability for coding transcripts, default is 0.5
-n		prior probability for noncoding transcripts, default is 0.5
-b 		bam nickname as the user designated in step 1 (writing Datasets.py)
-f		RPS model file path and prefix (positive and negative model file names must only differ at the end, and file names must contain 'RPS')

---------- output files:

hg19_PCG_lncRNA_by_HeLa_Ribobam.WRE		file with weighted relative entropy value
hg19_PCG_lncRNA_by_HeLa_Ribobam_PCG.RPS		file containing transcripts classified as coding by RPS and their RPS values
hg19_PCG_lncRNA_by_HeLa_Ribobam_NC.RPS		file containing transcripts classified as non-coding by RPS or transcripts without sufficient ribosome association
hg19_PCG_lncRNA_NC.refFlat			refFlat file of transcripts without coding potential, used as input of UAS in downstream

3) UPF1 association score (UAS)

---------- used script: 

TERIUS_part2.py 

Usage: python <scripts_dir>TERIUS_part2.py -l <cell_line> -r <refFlat> -s <scripts_dir> -o <output_dir> -e <lncRNA_prior> -u <UTR_prior> -t <UAS cutoff> -i <transcript_id_column_number> -d <RPM_column_number> -v <CLIPseq_bam_nickname> -z <RNAseq_bam_nickname>

This step calculates UPF1 association score to separate 3'UTR fragments from lncRNAs. 
UAS outputs posterior probabilty of transcripts like RPS.
If you have your own RPM files, you can specify them using -c for CLIP-seq RPM file and -a for RNA-seq RPM file. 
If you intend to use your own RPM files, you should specify the index of columns containing transcript/gene IDs and RPM values (0-based index).


---------- example: 

python TERIUS_part2.py  -l HeLa -r ../results_new/hg19_PCG_lncRNA_NC.refFlat -s ./ -o ../results_new/ -e 0.45 -u 0.55 -t 0.6 -v HeLa_UPF1bam -z HeLa_RNAbam -f ../dataset/models/UAS_meanModel_

---------- arguments:

-l		cell line used to generate CLIP-seq and RNA-seq library
-r		input refFlat
-s		scripts directory
-o		output directory
-e		prior probability of lncRNA, default is 0.5
-u		prior probability of 3'UTR fragments of mRNA, default is 0.5
-t		posterior probability cutoff for UAS, a number between 0 and 1, default is 0.5
-v		nickname of CLIP-seq bam as designated in step 1. At least one of -v and -c should be specified to run this step
-c		user-provided file containing CLIP-seq RPM of transcripts 
-z		nickname of RNA-seq bam as designated in step 1. At least one of -z and -a should be specified to run this step 
-a		user-provided file containing RNA-seq RPM of transcripts
-i		0-based column index of transcript/geneID in RPM/FPM file, default is 0
-d		0-based column index of RPM/FPM value in RPM/FPM file, default is 3
-f		UAS model file directory and file name prefix (file name must contain 'UAS' and positive model and negative model file names must only differ at the end)

---------- output files:

hg19_PCG_lncRNA_NC.refFlat		annotation file of transcripts classified as non-coding by RPS in refFlat format
HeLa_UPF1_hg19_PCG_lncRNA_NCgene.rpm	file with CLIP-seq/RNA-seq RPM values of transcritps, created in rpm/ folder under directory of bam files 
HeLa_UPF1_hg19_PCG_lncRNA_NCgene.UAStmp	file containing CLIP-seq RPM, RNA-seq RPM and UAS values of each transcripts
HeLa_UPF1_hg19_PCG_lncRNA_NCgene.UAS	file containing posterior probability of each transcripts
