New upstream version 1.6.1+dfsg

\begin{center}

{\Huge\bf Subread/Rsubread Users Guide}\\

\vspace{1 cm}

{\centering\large Subread v1.6.0/Rsubread v1.28.0\\}

{\centering\large Subread v1.6.1/Rsubread v1.29.1\\}

\vspace{1 cm}

\centering 14 Nov 2017\\

\centering 21 March 2018\\

\vspace{5 cm}

\Large Wei Shi and Yang Liao\\

\vspace{1 cm}

The University of Melbourne\\

Melbourne, Australia\\}

\vspace{7 cm}

\centering Copyright \small{\copyright}  2011 - 2017\\

\centering Copyright \small{\copyright}  2011 - 2018\\

\end{center}

\end{titlepage}

\chapter{Introduction}

The Subread/Rsubread packages comprise a suite of high-performance software programs for processing next-generation sequencing data.

Included in these packages are \code{Subread} aligner, \code{Subjunc} aligner, \code{Subindel} long indel detection program, \code{featureCounts} read quantification program, \code{exactSNP} SNP calling program and other utility programs.

Included in these packages are \code{Subread} aligner, \code{Subjunc} aligner, \code{Sublong} long-read aligner, \code{Subindel} long indel detection program, \code{featureCounts} read quantification program, \code{exactSNP} SNP calling program and other utility programs.

This document provides a detailed description to the programs included in the packages.

\code{Subread} and \code{Subjunc} aligners adopt a mapping paradigm called ``seed-and-vote'' \cite{liao}.

\hline

Arguments & Description \\

\hline

-a $<string>$\newline (\code{useAnnotation, annot.inbuilt, annot.ext}) & Name of a gene annotation file that includes chromosomal coordinates of exons from each gene. GTF/GFF format by default. See -F option for supported formats. Users may use the inbuilt annotations included in this package (SAF format) for human and mouse data. Exon-exon junctions are inferred by connecting each pair of neighboring exons from the same gene.\\

-a $<string>$\newline (\code{useAnnotation, annot.inbuilt, annot.ext}) & Name of a gene annotation file that includes chromosomal coordinates of exons from each gene. GTF/GFF format by default. See -F option for supported formats. Users may use the inbuilt annotations included in this package (SAF format) for human and mouse data. Exon-exon junctions are inferred by connecting each pair of neighboring exons from the same gene. Gzipped file is accepted. \\

\hline

-A $<string>$\newline (\code{chrAliases}) & Name of a comma-delimited text file that includes aliases of chromosome names. This file should contain two columns. First column contains names of chromosomes included in the SAF or GTF annotation and second column contains corresponding names of chromosomes in the reference genome. No column headers should be provided. Also note that chromosome names are case sensitive. This file can be used to match chromosome names between the annotation and the reference genome.\\

\hline

\hline

-F $<string>$ \newline (\code{isGTF}) & Specify format of the provided annotation file. Acceptable formats include `GTF' (or compatible GFF format) and `SAF'. Default format in SourceForge {\Subread} is `GTF'. Default format in {\Rsubread} is `SAF'.   \\

\hline

-i $<string> \newline (\code{index}) $ & Specify the base name of the index. Full index (not gapped index) must be provided for \code{sublong} aligner, ie. `-F' option must be specified when running \code{subread-buildindex} for index building.\\

-i $<string> \newline (\code{index}) $ & Specify the base name of the index. The index used by \code{sublong} aligner must be a full index and has only one block, ie. `-F' and `-B' options must be specified when building index with \code{subread-buildindex}.\\

\hline

-I $<int>$ \newline (\code{indels}) & Specify the number of INDEL bases allowed in the mapping. 5 by default. Indels of up to 200bp long can be detected.\\

\hline

\chapter{Mapping long sequence reads}

\section{Short description}

We developed a new long-read aligner called {\Sublong}, which is also based on the seed-and-vote mapping strategy.

{\Sublong} is an order of magnitude faster than existing long-read aligners.

Our simulation results also show that {\Sublong} performs better in mapping accuracy.

We have developed a new long-read aligner called {\Sublong}, which is also based on the seed-and-vote mapping strategy.

Parameters of {\Sublong} program can be found in Table 2.

If a read is both multi-mapping and multi-overlapping, then each overlapping meta-feature/feature will receive a fractional count of $1/(x*y)$ when `-O', `-M', and `--fraction' are all specified.

Note that each alignment reported for a multi-mapping read is assessed separately for overlapping with multiple meta-features/features.

When multi-mapping reads are reported with primary and secondary alignments and both `-M' and `--primary' are specified, only primary alignments will be considered in counting and secondary alignments will be ignored.

If `-M' is specified but `--primary' is not specified, both primary and secondary alignments will be considered in counting.

Note that all the alignments reported for a multi-mapping read are expected to have a `NH' tag and whether an alignment is primary or secondary is determined by using bit {0x100} in the FLAG field of the alignment record.

\subsection{Read filtering}

\label{sec:read_filtering}

\hline

input\_files \newline (\code{files}) & Give the names of input read files that include the read mapping results. The program automatically detects the file format (SAM or BAM). Multiple files can be provided at the same time. Files are allowed to be provided via $<stdin>$. \\

\hline

-a $<string>$ \newline (\code{annot.ext, annot.inbuilt})  & Give the name of an annotation file. \\

-a $<string>$ \newline (\code{annot.ext, annot.inbuilt})  & Provide name of an annotation file. See \code{-F} option for file format. Gzipped file is accepted.\\

\hline

-A \newline (\code{chrAliases}) & Provide a chromosome name alias file to match chr names in annotation with those in the reads. This should be a two-column comma-delimited text file. Its first column should include chr names in the annotation and its second column should include chr names in the reads. Chr names are case sensitive. No column header should be included in the file.\\

\hline

\hline

$--$fracOverlap $<float>$ \newline (\code{fracOverlap}) & Minimum fraction of overlapping bases in a read that is required for read assignment. Value should be a float number in the range [0,1]. 0 by default. If paired end, number of overlapping bases is counted from both reads. Soft-clipped bases are counted when calculating total read length (but ignored when counting overlapping bases). Both this option and `--minOverlap' option need to be satisfied for read assignment. \\

\hline

$--$fracOverlapFeature $<float>$ \newline (\code{fracOverlapFeature}) & Minimum fraction of bases included in a feature that is required for overlapping with a read or a read pair. Value should be within range [0,1]. 0 by default. \\

$--$fracOverlapFeature $<float>$ \newline (\code{fracOverlapFeature}) & Minimum fraction of bases included in a feature that is required to overlap with a read or a read pair. Value should be within range [0,1]. 0 by default. \\

\hline

$--$ignoreDup \newline (\code{ignoreDup}) & If specified, reads that were marked as duplicates will be ignored. Bit Ox400 in FLAG field of SAM/BAM file is used for identifying duplicate reads. In paired end data, the entire read pair will be ignored if at least one end is found to be a duplicate read.\\

\hline

\hline

$--$minOverlap $<int>$ \newline (\code{minOverlap}) & Minimum number of overlapping bases in a read that is required for read assignment. 1 by default. If a negative value is provided, then a gap of up to specified size will be allowed between read and the feature that the read is assigned to. For assignment of read pairs (fragments), number of overlapping bases from each read from the same pair will be summed. \\

\hline

$--$nonOverlap $<int>$ \newline (\code{nonOverlap}) & Maximum number of non-overlapping bases in a read (or a read pair) that is allowed when being assigned to a feature. No limit is set by default. \\

\hline

$--$nonOverlapFeature $<int>$ \newline (\code{nonOverlapFeature}) & Maximum number of non-overlapping bases in a feature that is allowed in read assignment. No limit is set by default. \\

\hline

$--$primary \newline (\code{primaryOnly}) & If specified, only primary alignments will be counted. Primary and secondary alignments are identified using bit 0x100 in the Flag field of SAM/BAM files. All primary alignments in a dataset will be counted no matter they are from multi-mapping reads or not (ie. `-M' is ignored).\\

\hline

$--$read2pos $<int>$ \newline (\code{read2pos}) & The read is reduced to its 5' most base or 3' most base. Read summarization is then performed based on the single base position to which the read is reduced. By default, no read reduction will be performed.\\

\hline

Arguments & Description \\

\hline

-a $<file>$ \newline (SNPAnnotationFile) & Specify name of a VCF-format file that includes annotated SNPs. Such annotation files can be downloaded from public databases such as the dbSNP database. Incorporating known SNPs into SNP calling has been found to be helpful. However note that the annotated SNPs may or may not be called for the sample being analyzed. \\

-a $<file>$ \newline (SNPAnnotationFile) & Specify name of a VCF-format file that includes annotated SNPs. Such annotation files can be downloaded from public databases such as the dbSNP database. Gzipped file is accepted. Incorporating known SNPs into SNP calling has been found to be helpful. However note that the annotated SNPs may or may not be called for the sample being analyzed. \\

\hline

-b \newline (isBAM) & Indicate the input file provided via $-i$ is in BAM format. \\

\hline

\hline

-v & Output version of the program. \\

\hline

-x $<int>$ \newline (maxReads) & Specify the maximum number of mapped reads a SNP-containing location could have. 3000 by default. Any location having more than the threshold number of reads will not be considered for SNP calling. This option is useful for removing PCR artefacts. \\

-x $<int>$ \newline (maxReads) & Specify the maximum depth a SNP location is allowed to have. 1,000,000 reads by default. Any location having more reads than the maximum allowed depth will not be considered for SNP calling. This option is useful for removing PCR artefacts. \\

\hline

\end{longtable}

#include "subread.h"

#include "input-files.h"

#include "seek-zlib.h"

#include "gene-algorithms.h"

#include "HelperFunctions.h"

	int cigar_cursor=0;

	unsigned short current_section_chro_len=0, current_section_start_read_pos = 0, read_cursor = 0;

	unsigned int chromosome_cursor=first_pos;

	int ret=0;

	int ret=0, is_first_S = 1;

	for(cigar_cursor=0; ; cigar_cursor++)

	{

		}

		else

		{

			if(ch == 'S')

			if(ch == 'S'){

				if(is_first_S) current_section_start_read_pos = tmp_int;

				read_cursor += tmp_int;

			}

			else if(ch == 'M' || ch == 'X' || ch == '=') {

				read_cursor += tmp_int;

				current_section_chro_len += tmp_int;

			}

			//printf("C=%c, TV=%d, CC=%d, RC=%d\n", ch, tmp_int, chromosome_cursor, current_section_chro_len);

			tmp_int = 0;

			is_first_S = 0;

		}

		if(cigar_cursor>100) return -1;

	}

}

int mathrand_str(char * str_buff){

	srand((int)(miltime()*100));

	myrand_srand((int)(miltime()*100));

	int x1;

	for(x1 = 0; x1 < 6; x1++){

		sprintf(str_buff+2*x1, "%02X", rand() & 0xff );

		sprintf(str_buff+2*x1, "%02X", myrand_rand() & 0xff );

	}

	return 0;

}

 void * context, int do_add_feature(char * gene_name, char * transcript_name, char * chro_name, unsigned int start, unsigned int end, int is_negative_strand, void * context)  ){

	char * file_line = malloc(MAX_LINE_LENGTH+1);

	int lineno = 0, is_GFF_txid_warned = 0, is_GFF_geneid_warned = 0, loaded_features = 0;

	FILE * fp = fopen(file_name, "r");

	autozip_fp afp;

	int aret = autozip_open(file_name, &afp);

	if(NULL == fp){

	if(aret < 0){

		SUBREADprintf("Error: unable to open the annotation file : %s\n", file_name);

		return -1;

	}

		feature_name = feature_name_tmp;

		unsigned int start = 0, end = 0;

		char * getres = fgets(file_line, MAX_LINE_LENGTH, fp);

		if(getres == NULL) break;

		aret = autozip_gets(&afp, file_line, MAX_LINE_LENGTH);

		if(aret < 1) break;

		lineno++;

		if(is_comment_line(file_line, file_type, lineno-1))continue;

		}

	}

	fclose(fp);

	autozip_close(&afp);

	free(file_line);		

	return loaded_features;

}

all: sublong repair featureCounts removeDup exactSNP subread-buildindex subindel  subread-align subjunc  subtools qualityScores  subread-fullscan propmapped  coverageCount 

	mkdir -p ../bin/utilities

	mv sublong subread-align subjunc featureCounts  subindel exactSNP subread-buildindex ../bin/

	mv longread-one/LRM longread-one/sublong

	mv longread-one/sublong subread-align subjunc featureCounts  subindel exactSNP subread-buildindex ../bin/

	mv repair  coverageCount subtools qualityScores propmapped subread-fullscan removeDup ../bin/utilities

	@echo

	@echo "###########################################################"

	@echo "###########################################################"

	@echo

sublong: longread-mapping/longread-mapping.c  ${ALL_OBJECTS}

	echo "MACOS= -D FREEBSD  " > longread-mapping/make.version

	rm -f longread-mapping/*.o

	cd longread-mapping && $(MAKE)

sublong: longread-one/longread-mapping.c  ${ALL_OBJECTS}

	echo "MACOS= -D FREEBSD  " > longread-one/make.version

	rm -f longread-one/*.o

	cd longread-one && $(MAKE)

repair: read-repair.c ${ALL_OBJECTS}

	${CC} -o repair read-repair.c ${ALL_OBJECTS} ${LDFLAGS}

ALL_H=$(addsuffix .h, ${ALL_LIBS})

ALL_C=$(addsuffix .c, ${ALL_LIBS})

all: sublong repair txUnique featureCounts removeDup exactSNP subread-buildindex subindel  subread-align subjunc qualityScores subread-fullscan propmapped coverageCount  # samMappedBases mergeVCF  testZlib

all: detectionCall sublong repair txUnique featureCounts removeDup exactSNP subread-buildindex subindel  subread-align subjunc qualityScores subread-fullscan propmapped coverageCount  # samMappedBases mergeVCF  testZlib

	mkdir -p ../bin/utilities

	mv sublong subread-align subjunc featureCounts  subindel exactSNP subread-buildindex ../bin/

	mv repair coverageCount propmapped qualityScores removeDup subread-fullscan txUnique ../bin/utilities

	mv longread-one/LRM longread-one/sublong

	mv longread-one/sublong subread-align subjunc featureCounts  subindel exactSNP subread-buildindex ../bin/

	mv detectionCall repair coverageCount propmapped qualityScores removeDup subread-fullscan txUnique ../bin/utilities

	@echo

	@echo "###########################################################"

	@echo "#                                                         #"

	@echo "###########################################################"

	@echo

sublong: longread-mapping/longread-mapping.c  ${ALL_OBJECTS}

	echo " " > longread-mapping/make.version

	rm -f longread-mapping/*.o

	cd longread-mapping && $(MAKE)

sublong: longread-one/longread-mapping.c  ${ALL_OBJECTS}

	echo " " > longread-one/make.version

	rm -f longread-one/*.o

	cd longread-one && $(MAKE)

detectionCall: detection-calls.c	 ${ALL_OBJECTS}

	${CC} -o detectionCall detection-calls.c  ${ALL_OBJECTS} ${LDFLAGS}

repair: read-repair.c	 ${ALL_OBJECTS}

	${CC} -o repair read-repair.c  ${ALL_OBJECTS} ${LDFLAGS}

all: sublong repair featureCounts removeDup exactSNP subread-buildindex subindel  subread-align subjunc qualityScores subread-fullscan propmapped coverageCount # globalReassembly testZlib

	mkdir -p ../bin/utilities

	mv sublong subread-align subjunc featureCounts  subindel exactSNP subread-buildindex ../bin/

	mv longread-one/LRM longread-one/sublong

	mv longread-one/sublong subread-align subjunc featureCounts  subindel exactSNP subread-buildindex ../bin/

	mv repair coverageCount subread-fullscan qualityScores removeDup propmapped ../bin/utilities

	@echo

	@echo "###########################################################"

	@echo "###########################################################"

	@echo

sublong: longread-mapping/longread-mapping.c  ${ALL_OBJECTS}

	echo "MACOS= -D MACOS " > longread-mapping/make.version

	rm -f longread-mapping/*.o

	cd longread-mapping && $(MAKE)

sublong: longread-one/longread-mapping.c  ${ALL_OBJECTS}

	echo "MACOS= -D MACOS " > longread-one/make.version

	rm -f longread-one/*.o

	cd longread-one && $(MAKE)

repair: read-repair.c ${ALL_OBJECTS}

	${CC} -o repair read-repair.c ${ALL_OBJECTS} ${LDFLAGS}