% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/CollateData.R
\name{CollateData}
\alias{CollateData}
\title{Processes data from IRFinder output}
\usage{
CollateData(
  Experiment,
  reference_path,
  output_path,
  IRMode = c("SpliceOverMax", "SpliceMax"),
  overwrite = FALSE,
  n_threads = 1,
  samples_per_block = 16
)
}
\arguments{
\item{Experiment}{(Required) A 2 or 3 column data frame, ideally generated by
\link{Find_IRFinder_Output} or \link{Find_Samples}.
The first column designate the sample names, and the 2nd column
contains the path to the IRFinder output file (of type \code{sample.txt.gz}).
(Optionally) a 3rd column contains the coverage files (of type
\code{sample.cov}) of the corresponding samples.
NB: all other columns are ignored.}

\item{reference_path}{(Required) The path to the reference generated by
\link{BuildReference}}

\item{output_path}{(Required)  The path to contain the output files for this
function}

\item{IRMode}{(default \code{SpliceOverMax}) The algorithm to calculate
'splice abundance' in IR quantification.
Valid options are \code{SpliceOverMax} and \code{SpliceMax}.
See details}

\item{overwrite}{(default \code{FALSE}) If \code{CollateData()} has previously been run
using the same set of samples, it will not be overwritten unless this is
set to \code{TRUE}.}

\item{n_threads}{(default \code{1}) The number of threads to use. On low
memory systems, reduce the number of \code{n_threads} and \code{samples_per_block}}

\item{samples_per_block}{(default \code{16}) How many samples to process per
thread, maximum. Setting this to a lower value may help in
memory-constrained systems.}
}
\value{
\code{CollateData()} writes to the directory given by \code{output_path}.
This output directory is portable (i.e. it can be moved to a different
location after running \code{CollateData()} before running \link{MakeSE}), but
individual files within the output folder should not be moved.\cr\cr
Also, the \link{IRFinder} and \link{CollateData} output folders should be copied to
the same destination and their relative paths preserved. Otherwise, the
locations of the "COV" files will not be recorded in the collated data and
will have to be re-assigned using \verb{covfile(se)<-}. See \link{MakeSE}
}
\description{
CollateData unifies a list of \link{IRFinder} output files belonging to an
experiment.
}
\details{
All sample IRFinder outputs must be generated using the same
reference.

The combination of junction counts and IR quantification from
IRFinder is used to calculate percentage spliced in (PSI) of alternative
splice events, and percent intron retention (PIR) of retained introns. Also,
QC information is extracted. Data is organised in a H5file and FST files
for memory and processor efficient downstream access using \link{MakeSE}.

The original IRFinder algorithm, see the following
\href{https://github.com/williamritchie/IRFinder/wiki/IRFinder-Output}{wiki},
uses \code{SpliceMax} to estimate abundance of spliced transcripts.
This calculates the number of mapped splice events
that share the boundary coordinate of either the left or right flanking
exon \verb{SpliceLeft,SpliceRight}, estimating splice abundance as the larger
of the two values.

NxtIRF proposes a new algorithm,\code{SpliceOverMax},
to account for the possibility that the major isoform shares neither
boundary, but arises from either of the flanking "exon islands". Exon
islands are contiguous regions covered by exons from any transcript
(except those designated as \code{retained_intron} or
\code{sense_intronic}), and are separated by
obligate intronic regions (genomic regions that are introns for all
transcripts). For introns that are internal to a single exon island
(i.e. akin to "known-exon" introns from IRFinder), \code{SpliceOverMax}
uses \link[GenomicRanges:findOverlaps-methods]{GenomicRanges::findOverlaps} to sum all splice reads that overlap
the same genomic region as the intron of interest.
}
\examples{
BuildReference(
    reference_path = file.path(tempdir(), "Reference"),
    fasta = chrZ_genome(),
    gtf = chrZ_gtf()
)

bams <- NxtIRF_example_bams()
IRFinder(bams$path, bams$sample,
  reference_path = file.path(tempdir(), "Reference"),
  output_path = file.path(tempdir(), "IRFinder_output")
)

expr <- Find_IRFinder_Output(file.path(tempdir(), "IRFinder_output"))
CollateData(expr,
  reference_path = file.path(tempdir(), "Reference"),
  output_path = file.path(tempdir(), "NxtIRF_output")
)
}
\seealso{
\link{IRFinder}, \link{MakeSE}
}
