@@ -19,8 +19,9 @@

 \usage{

 \S4method{bam_tally}{BamFile}(x, param, ...)

 \S4method{bam_tally}{character}(x, param, ...)

-variantSummary(x, read_pos_breaks = NULL, high_base_quality = 0L,

-               keep_ref_rows = FALSE, read_length = NA_integer_)

+variantSummary(x, read_pos_breaks = NULL,

+               keep_ref_rows = FALSE, read_length = NA_integer_,

+               high_nm_score = NA_integer_)

 }

 \arguments{

@@ -30,8 +31,6 @@ variantSummary(x, read_pos_breaks = NULL, high_base_quality = 0L,

   \item{read_pos_breaks}{The breaks, like those passed to \code{\link{cut}}

     for aggregating the per-read position counts. If \code{NULL}, no per-cycle

     counts are returned.}

-  \item{high_base_quality}{The minimum mapping quality for a

-    read to be counted as high quality.}

   \item{keep_ref_rows}{Whether to keep the rows describing only the

     reference calls, i.e., where ref and alt are the same. These are

     useful when one needs the reference counts even when there are no

@@ -39,6 +38,7 @@ variantSummary(x, read_pos_breaks = NULL, high_base_quality = 0L,

   \item{read_length}{The expected read length. If the read length is NA,

     the MDFNE (median distance from nearest end) statistic will NOT be

     calculated.}

+  \item{high_nm_score}{The value at which an NM value is considered high.}

   \item{...}{Arguments that override settings in \code{param}.}

 }

@@ -55,15 +55,8 @@ variantSummary(x, read_pos_breaks = NULL, high_base_quality = 0L,

   columns are also present:

   \item{n.read.pos}{The number of unique read positions for the alt allele.}

   \item{n.read.pos.ref}{The number of unique read positions for the ref allele.}

-  \item{raw.count}{The number of reads with the alternate allele,

-    \code{NA} for the reference allele row.}

-  \item{raw.count.ref}{The number of reads with the reference allele.}

   \item{raw.count.total}{The total number of reads at that position,

     including reference and all alternates.}

-  \item{mean.quality}{The mean base quality for the alt allele,

-    truncated at \code{high_base_quality}.}

-  \item{mean.quality.ref}{The mean base quality for the ref allele,

-    truncated at \code{high_base_quality}.}

   \item{count.plus}{The number of positive strand reads for the alternate

     allele, \code{NA} for the reference allele row.}

   \item{count.plus.ref}{The number of positive strand reads for the reference

@@ -72,12 +65,28 @@ variantSummary(x, read_pos_breaks = NULL, high_base_quality = 0L,

     allele, \code{NA} for the reference allele row.}

   \item{count.minus.ref}{The number of negative strand reads for the reference

     allele.}

+  \item{count.del.plus}{The plus strand deletion count over the

+    position.}

+  \item{count.del.minus}{The minus strand deletion count over the

+    position.}

   \item{read.pos.mean}{Mean read position for the alt allele.}

   \item{read.pos.mean.ref}{Mean read position for the ref allele.}

   \item{read.pos.var}{Variance in the read positions for the alt allele.}

   \item{read.pos.var.ref}{Variance in the read positions for the ref allele.}

   \item{mdfne}{Median distance from nearest end for the alt allele.}

   \item{mdfne.ref}{Median distance from nearest end for the ref allele.}

+  \item{count.high.nm}{The number of alt reads with an NM value at or above the

+    \code{high_nm_score} cutoff.}

+  \item{count.high.nm.ref}{The number of ref reads with an NM value at

+    or above the \code{high_nm_score} cutoff.}

+  

+  If codon counting was enabled, there will be a column giving the codon

+  strand: \code{codon.strand}.

+  

+  If the \code{xs} parameter was \code{TRUE}, there will be four

+  additional columns giving the counts by aligner-determined

+  strand: \code{count.xs.plus}, \code{count.xs.plus.ref},

+  \code{count.xs.minus}, and \code{count.xs.minus.ref}.

   An additional column is present for each bin formed by

   the \code{read_pos_breaks} parameter, with the read count for that bin.

@@ -53,6 +53,8 @@ variantSummary(x, read_pos_breaks = NULL, high_base_quality = 0L,

   after quality filtering (except for indels, for which there is no

   quality filtering). The following \code{elementMetadata}

   columns are also present:

+  \item{n.read.pos}{The number of unique read positions for the alt allele.}

+  \item{n.read.pos.ref}{The number of unique read positions for the ref allele.}

   \item{raw.count}{The number of reads with the alternate allele,

     \code{NA} for the reference allele row.}

   \item{raw.count.ref}{The number of reads with the reference allele.}

@@ -36,11 +36,9 @@ variantSummary(x, read_pos_breaks = NULL, high_base_quality = 0L,

     reference calls, i.e., where ref and alt are the same. These are

     useful when one needs the reference counts even when there are no

     alts at that position.}

-  \item{read_length}{The expected read length. If NA, a best guess is

-    made by inspecting a random sample from the BAM file. If the read

-    length is determined to be variable, the

-    MDFNE (median distance from nearest end) statistic will NOT

-    be calculated.}

+  \item{read_length}{The expected read length. If the read length is NA,

+    the MDFNE (median distance from nearest end) statistic will NOT be

+    calculated.}

   \item{...}{Arguments that override settings in \code{param}.}

 }

@@ -20,7 +20,7 @@

 \S4method{bam_tally}{BamFile}(x, param, ...)

 \S4method{bam_tally}{character}(x, param, ...)

 variantSummary(x, read_pos_breaks = NULL, high_base_quality = 0L,

-               keep_ref_rows = FALSE)

+               keep_ref_rows = FALSE, read_length = NA_integer_)

 }

 \arguments{

@@ -36,6 +36,11 @@ variantSummary(x, read_pos_breaks = NULL, high_base_quality = 0L,

     reference calls, i.e., where ref and alt are the same. These are

     useful when one needs the reference counts even when there are no

     alts at that position.}

+  \item{read_length}{The expected read length. If NA, a best guess is

+    made by inspecting a random sample from the BAM file. If the read

+    length is determined to be variable, the

+    MDFNE (median distance from nearest end) statistic will NOT

+    be calculated.}

   \item{...}{Arguments that override settings in \code{param}.}

 }

@@ -55,9 +55,10 @@ variantSummary(x, read_pos_breaks = NULL, high_base_quality = 0L,

   \item{raw.count.ref}{The number of reads with the reference allele.}

   \item{raw.count.total}{The total number of reads at that position,

     including reference and all alternates.}

-  \item{mean.quality}{The mean mapping quality for the alt allele.}

-  \item{mean.quality.ref}{The mean mapping quality for the reference

-    allele.}

+  \item{mean.quality}{The mean base quality for the alt allele,

+    truncated at \code{high_base_quality}.}

+  \item{mean.quality.ref}{The mean base quality for the ref allele,

+    truncated at \code{high_base_quality}.}

   \item{count.plus}{The number of positive strand reads for the alternate

     allele, \code{NA} for the reference allele row.}

   \item{count.plus.ref}{The number of positive strand reads for the reference

@@ -50,27 +50,28 @@ variantSummary(x, read_pos_breaks = NULL, high_base_quality = 0L,

   after quality filtering (except for indels, for which there is no

   quality filtering). The following \code{elementMetadata}

   columns are also present:

-  \item{n.read.pos}{The number of unique cycles at which the alternate allele was

-    observed, \code{NA} for the reference allele row.}

-  \item{n.read.pos.ref}{The number of unique cycles at which the reference

-    allele was observed.}

   \item{raw.count}{The number of reads with the alternate allele,

     \code{NA} for the reference allele row.}

   \item{raw.count.ref}{The number of reads with the reference allele.}

   \item{raw.count.total}{The total number of reads at that position,

     including reference and all alternates.}

+  \item{mean.quality}{The mean mapping quality for the alt allele.}

   \item{mean.quality.ref}{The mean mapping quality for the reference

     allele.}

-  \item{count.pos}{The number of positive strand reads for the alternate

+  \item{count.plus}{The number of positive strand reads for the alternate

     allele, \code{NA} for the reference allele row.}

-  \item{count.pos.ref}{The number of positive strand reads for the reference

+  \item{count.plus.ref}{The number of positive strand reads for the reference

     allele.}

-  \item{count.neg}{The number of negative strand reads for the alternate

+  \item{count.minus}{The number of negative strand reads for the alternate

     allele, \code{NA} for the reference allele row.}

-  \item{count.neg.ref}{The number of negative strand reads for the reference

+  \item{count.minus.ref}{The number of negative strand reads for the reference

     allele.}

+  \item{read.pos.mean}{Mean read position for the alt allele.}

+  \item{read.pos.mean.ref}{Mean read position for the ref allele.}

   \item{read.pos.var}{Variance in the read positions for the alt allele.}

   \item{read.pos.var.ref}{Variance in the read positions for the ref allele.}

+  \item{mdfne}{Median distance from nearest end for the alt allele.}

+  \item{mdfne.ref}{Median distance from nearest end for the ref allele.}

   An additional column is present for each bin formed by

   the \code{read_pos_breaks} parameter, with the read count for that bin.

@@ -4,7 +4,9 @@

 \alias{bam_tally,BamFile-method}

 \alias{bam_tally,character-method}

 \alias{bam_tally,GmapBamReader-method}

+\alias{genome,TallyIIT-method}

 \alias{bam_tally}

+\alias{variantSummary}

 \title{Per-position Alignment Summaries}

@@ -17,41 +19,46 @@

 \usage{

 \S4method{bam_tally}{BamFile}(x, param, ...)

 \S4method{bam_tally}{character}(x, param, ...)

+variantSummary(x, read_pos_breaks = NULL, high_base_quality = 0L,

+               keep_ref_rows = FALSE)

 }

 \arguments{

   \item{x}{a \code{BamFile} object or string path to a BAM file to read}

   \item{param}{The \code{\linkS4class{BamTallyParam}} object with

     parameters for the tally operation. }

+  \item{read_pos_breaks}{The breaks, like those passed to \code{\link{cut}}

+    for aggregating the per-read position counts. If \code{NULL}, no per-cycle

+    counts are returned.}

+  \item{high_base_quality}{The minimum mapping quality for a

+    read to be counted as high quality.}

+  \item{keep_ref_rows}{Whether to keep the rows describing only the

+    reference calls, i.e., where ref and alt are the same. These are

+    useful when one needs the reference counts even when there are no

+    alts at that position.}

   \item{...}{Arguments that override settings in \code{param}.}

 }

 \value{

-  A \code{\link[GenomicRanges]{GRanges}}, with a range for each position

-  that passed the filters, and with the following \code{elementMetadata}

-  columns:

-  \item{location}{A string representation of the location, of the form

-    \dQuote{chr:pos}. This makes it easy, e.g., to check for the

-    presence of a variant in another result object.}

-  \item{ref}{The reference base at that position.}

-  \item{alt}{The base for the alternate allele, \code{NA} for the

-    reference allele row.}

+  The \code{bam_tally} function returns an opaque pointer to a C-level

+  data structure with the class \dQuote{TallyIIT}. Currently, the only

+  operation applicable to this object is \code{variantSummary}.

+  

+  The \code{variantSummary} function returns

+  a \code{\link[VariantAnnotation]{VRanges}}, with a range for each position

+  that passed the filters. The depth columns correspond to the counts

+  after quality filtering (except for indels, for which there is no

+  quality filtering). The following \code{elementMetadata}

+  columns are also present:

   \item{n.read.pos}{The number of unique cycles at which the alternate allele was

     observed, \code{NA} for the reference allele row.}

   \item{n.read.pos.ref}{The number of unique cycles at which the reference

     allele was observed.}

-  \item{count}{The number of reads with the alternate allele,

+  \item{raw.count}{The number of reads with the alternate allele,

     \code{NA} for the reference allele row.}

-  \item{count.ref}{The number of reads with the reference allele.}

-  \item{count.total}{The total number of reads at that position,

+  \item{raw.count.ref}{The number of reads with the reference allele.}

+  \item{raw.count.total}{The total number of reads at that position,

     including reference and all alternates.}

-  \item{high.quality}{The number of reads for the alternate allele that were

-    above \code{high_quality_cutoff}, \code{NA} for the reference allele

-    row.}

-  \item{high.quality.ref}{The number of reads for the reference allele that were

-    above \code{high_quality_cutoff}.}

-  \item{mean.quality}{The mean mapping quality for the alternate allele,

-    \code{NA} for the reference allele row.}

   \item{mean.quality.ref}{The mean mapping quality for the reference

     allele.}

   \item{count.pos}{The number of positive strand reads for the alternate

@@ -62,9 +69,14 @@

     allele, \code{NA} for the reference allele row.}

   \item{count.neg.ref}{The number of negative strand reads for the reference

     allele.}

-

+  \item{read.pos.var}{Variance in the read positions for the alt allele.}

+  \item{read.pos.var.ref}{Variance in the read positions for the ref allele.}

+  

   An additional column is present for each bin formed by

   the \code{read_pos_breaks} parameter, with the read count for that bin.

 }

+\seealso{\code{tallyVariants} in the VariantTools package provides a

+  high-level wrapper for this functionality.}

+

 \author{Michael Lawrence}

@@ -36,9 +36,9 @@

   \item{ref}{The reference base at that position.}

   \item{alt}{The base for the alternate allele, \code{NA} for the

     reference allele row.}

-  \item{ncycles}{The number of unique cycles at which the alternate allele was

+  \item{n.read.pos}{The number of unique cycles at which the alternate allele was

     observed, \code{NA} for the reference allele row.}

-  \item{ncycles.ref}{The number of unique cycles at which the reference

+  \item{n.read.pos.ref}{The number of unique cycles at which the reference

     allele was observed.}

   \item{count}{The number of reads with the alternate allele,

     \code{NA} for the reference allele row.}

@@ -64,7 +64,7 @@

     allele.}

   An additional column is present for each bin formed by

-  the \code{cycle_breaks} parameter, with the read count for that bin.

+  the \code{read_pos_breaks} parameter, with the read count for that bin.

 }

 \author{Michael Lawrence}

@@ -6,8 +6,8 @@

 \alias{bam_tally,GmapBamReader-method}

 \alias{bam_tally}

-\title{Create a Summarization of the Read Sequences and Qualities for Each

-  Genomic Position}

+\title{Per-position Alignment Summaries}

+

 \description{

   Given a set of alignments, for each position in the genome output

   counts for the reference allele and all alternate alleles. Often used

@@ -15,15 +15,13 @@

 }

 \usage{

-\S4method{bam_tally}{BamFile}(x, genome, param = BamTallyParam(), ...)

-\S4method{bam_tally}{character}(x, genome, param = BamTallyParam(), ...)

+\S4method{bam_tally}{BamFile}(x, param, ...)

+\S4method{bam_tally}{character}(x, param, ...)

 }

 \arguments{

   \item{x}{a \code{BamFile} object or string path to a BAM file to read}

-  \item{genome}{the \code{GmapGenome} object corresponding to the

-    alignments in the BAM file}

-  \item{param}{The \code{\linkS4class{BamTallyParam}} object with extra

+  \item{param}{The \code{\linkS4class{BamTallyParam}} object with

     parameters for the tally operation. }

   \item{...}{Arguments that override settings in \code{param}.}

 }

new file mode 100644

@@ -0,0 +1,72 @@

+\name{bam_tally-methods}

+\docType{methods}

+\alias{bam_tally-methods}

+\alias{bam_tally,BamFile-method}

+\alias{bam_tally,character-method}

+\alias{bam_tally,GmapBamReader-method}

+\alias{bam_tally}

+

+\title{Create a Summarization of the Read Sequences and Qualities for Each

+  Genomic Position}

+\description{

+  Given a set of alignments, for each position in the genome output

+  counts for the reference allele and all alternate alleles. Often used

+  as a precursor to detecting variants. Indels will be supported soon.

+}

+

+\usage{

+\S4method{bam_tally}{BamFile}(x, genome, param = BamTallyParam(), ...)

+\S4method{bam_tally}{character}(x, genome, param = BamTallyParam(), ...)

+}

+

+\arguments{

+  \item{x}{a \code{BamFile} object or string path to a BAM file to read}

+  \item{genome}{the \code{GmapGenome} object corresponding to the

+    alignments in the BAM file}

+  \item{param}{The \code{\linkS4class{BamTallyParam}} object with extra

+    parameters for the tally operation. }

+  \item{...}{Arguments that override settings in \code{param}.}

+}

+

+\value{

+  A \code{\link[GenomicRanges]{GRanges}}, with a range for each position

+  that passed the filters, and with the following \code{elementMetadata}

+  columns:

+  \item{location}{A string representation of the location, of the form

+    \dQuote{chr:pos}. This makes it easy, e.g., to check for the

+    presence of a variant in another result object.}

+  \item{ref}{The reference base at that position.}

+  \item{alt}{The base for the alternate allele, \code{NA} for the

+    reference allele row.}

+  \item{ncycles}{The number of unique cycles at which the alternate allele was

+    observed, \code{NA} for the reference allele row.}

+  \item{ncycles.ref}{The number of unique cycles at which the reference

+    allele was observed.}

+  \item{count}{The number of reads with the alternate allele,

+    \code{NA} for the reference allele row.}

+  \item{count.ref}{The number of reads with the reference allele.}

+  \item{count.total}{The total number of reads at that position,

+    including reference and all alternates.}

+  \item{high.quality}{The number of reads for the alternate allele that were

+    above \code{high_quality_cutoff}, \code{NA} for the reference allele

+    row.}

+  \item{high.quality.ref}{The number of reads for the reference allele that were

+    above \code{high_quality_cutoff}.}

+  \item{mean.quality}{The mean mapping quality for the alternate allele,

+    \code{NA} for the reference allele row.}

+  \item{mean.quality.ref}{The mean mapping quality for the reference

+    allele.}

+  \item{count.pos}{The number of positive strand reads for the alternate

+    allele, \code{NA} for the reference allele row.}

+  \item{count.pos.ref}{The number of positive strand reads for the reference

+    allele.}

+  \item{count.neg}{The number of negative strand reads for the alternate

+    allele, \code{NA} for the reference allele row.}

+  \item{count.neg.ref}{The number of negative strand reads for the reference

+    allele.}

+

+  An additional column is present for each bin formed by

+  the \code{cycle_breaks} parameter, with the read count for that bin.

+}

+

+\author{Michael Lawrence}