From f3cc08cf2da3dae9a80c1a6f42ec7407d5e196b4 Mon Sep 17 00:00:00 2001 From: vjcitn Date: Fri, 17 Jul 2026 21:15:29 -0400 Subject: [PATCH 1/3] fix Rd warnings: \itemize -> \describe and add non-empty labels Convert \itemize blocks that used \item{label}{desc} syntax to \describe, and replace empty \item{}{} labels in \describe blocks with the function signature from the body, resolving all checkRd warnings in isSNV-methods, PolyPhenDb-class, readVcf-methods, SIFTDb-class, summarizeVariants-methods, VariantType-class, VCF-class, VcfFile-class, VCFHeader-class, VRanges-class, and VRangesList-class Rd files. Co-Authored-By: Claude Sonnet 4.6 --- man/PolyPhenDb-class.Rd | 25 ++--- man/SIFTDb-class.Rd | 14 +-- man/VCF-class.Rd | 159 ++++++++++++++----------------- man/VCFHeader-class.Rd | 47 ++++----- man/VRanges-class.Rd | 93 +++++++++--------- man/VRangesList-class.Rd | 14 ++- man/VariantType-class.Rd | 21 ++-- man/VcfFile-class.Rd | 30 +++--- man/isSNV-methods.Rd | 12 +-- man/readVcf-methods.Rd | 14 +-- man/summarizeVariants-methods.Rd | 16 ++-- 11 files changed, 201 insertions(+), 244 deletions(-) diff --git a/man/PolyPhenDb-class.Rd b/man/PolyPhenDb-class.Rd index 28d92e4..f13e7cf 100644 --- a/man/PolyPhenDb-class.Rd +++ b/man/PolyPhenDb-class.Rd @@ -22,32 +22,27 @@ \section{Methods}{ In the code below, \code{x} is a \code{PolyPhenDb} object. \describe{ - \item{}{ - \code{metadata(x)}: + \item{\code{metadata(x)}}{ Returns \code{x}'s metadata in a data frame. } - \item{}{ - \code{columns(x)}: + \item{\code{columns(x)}}{ Returns the names of the \code{columns} that can be used to subset the data columns. For column descriptions see \code{?PolyPhenDbColumns}. } - \item{}{ - \code{keys(x)}: + \item{\code{keys(x)}}{ Returns the names of the \code{keys} that can be used to subset the data rows. The \code{keys} values are the rsid's. } - \item{}{ - \code{select(x, keys = NULL, columns = NULL, ...)}: - Returns a subset of data defined by the character vectors \code{keys} + \item{\code{select(x, keys = NULL, columns = NULL, ...)}}{ + Returns a subset of data defined by the character vectors \code{keys} and \code{columns}. If no \code{keys} are supplied, all rows are returned. If no \code{columns} are supplied, all columns are returned. See \code{?PolyPhenDbColumns} for column descriptions. - } - \item{}{ - \code{duplicateRSID(x)}: - Returns a named list of duplicate rsid groups. The names are the - \code{keys}, the list elements are the rsid's that have been - reported as having identical chromosome position and alleles and + } + \item{\code{duplicateRSID(x)}}{ + Returns a named list of duplicate rsid groups. The names are the + \code{keys}, the list elements are the rsid's that have been + reported as having identical chromosome position and alleles and therefore translating into the same amino acid residue substitution. } } diff --git a/man/SIFTDb-class.Rd b/man/SIFTDb-class.Rd index b695259..c2c7310 100644 --- a/man/SIFTDb-class.Rd +++ b/man/SIFTDb-class.Rd @@ -21,23 +21,19 @@ \section{Methods}{ In the code below, \code{x} is a \code{SIFTDb} object. \describe{ - \item{}{ - \code{metadata(x)}: + \item{\code{metadata(x)}}{ Returns \code{x}'s metadata in a data frame. } - \item{}{ - \code{columns(x)}: + \item{\code{columns(x)}}{ Returns the names of the \code{columns} that can be used to subset the data columns. } - \item{}{ - \code{keys(x)}: + \item{\code{keys(x)}}{ Returns the names of the \code{keys} that can be used to subset the data rows. The \code{keys} values are the rsid's. } - \item{}{ - \code{select(x, keys = NULL, columns = NULL, ...)}: - Returns a subset of data defined by the character vectors \code{keys} + \item{\code{select(x, keys = NULL, columns = NULL, ...)}}{ + Returns a subset of data defined by the character vectors \code{keys} and \code{columns}. If no \code{keys} are supplied, all rows are returned. If no \code{columns} are supplied, all columns are returned. For column descriptions see \code{?SIFTDbColumns}. diff --git a/man/VCF-class.Rd b/man/VCF-class.Rd index 59c8ee3..aa4847d 100644 --- a/man/VCF-class.Rd +++ b/man/VCF-class.Rd @@ -104,14 +104,13 @@ \section{Constructors}{ \describe{ - \item{}{ - \code{readVcf(file, genome, param, ..., row.names=TRUE)} + \item{\code{readVcf(file, genome, param, ..., row.names=TRUE)}}{ } - \item{}{ - \code{VCF(rowRanges = GRanges(), colData = DataFrame(), - exptData = list(header = VCFHeader()), - fixed = DataFrame(), info = DataFrame(), - geno = SimpleList(), ..., collapsed=TRUE, + \item{\code{VCF(rowRanges, colData, exptData, fixed, info, geno, ...)}}{ + \code{VCF(rowRanges = GRanges(), colData = DataFrame(), + exptData = list(header = VCFHeader()), + fixed = DataFrame(), info = DataFrame(), + geno = SimpleList(), ..., collapsed=TRUE, verbose = FALSE)} Creates CollapsedVCF when \code{collapsed = TRUE} and an ExpandedVCF when \code{collapsed = FALSE}. @@ -126,8 +125,7 @@ In the following code snippets \code{x} is a CollapsedVCF or ExpandedVCF object. \describe{ - \item{}{ - \code{rowRanges(x, ..., fixed = TRUE)}, \code{rowRanges(x) <- value}: + \item{\code{rowRanges(x, ..., fixed = TRUE)}, \code{rowRanges(x) <- value}}{ Gets or sets the rowRanges. The CHROM, POS, ID, POS and REF fields are used to create a \code{GRanges} object. The start of the ranges are defined by POS and the width is equal to the width of the reference @@ -135,10 +133,10 @@ \sQuote{.}) a string of CHROM:POS_REF/ALT is used instead. The \code{genome} argument is stored in the seqinfo of the \code{GRanges} and can be accessed with \code{genome()}. - - When \code{fixed = TRUE}, REF, ALT, QUAL and FILTER metadata columns are + + When \code{fixed = TRUE}, REF, ALT, QUAL and FILTER metadata columns are displayed as metadata columns. To modify the \code{fixed} fields, use - the \code{fixed<-} setter. + the \code{fixed<-} setter. One metadata column, \code{paramRangeID}, is included with the \code{rowRanges}. This ID is meaningful when multiple ranges are @@ -146,103 +144,93 @@ match each range. The metadata columns of a VCF object are accessed with the following: - \itemize{ - \item{\code{ref(x)}, \code{ref(x) <- value}: - Gets or sets the reference allele (REF). \code{value} must - be a \code{DNAStringSet}. + \describe{ + \item{\code{ref(x)}, \code{ref(x) <- value}:}{ + Gets or sets the reference allele (REF). \code{value} must + be a \code{DNAStringSet}. } - \item{\code{alt(x)}, \code{alt(x) <- value}: - Gets or sets the alternate allele data (ALT). When \code{x} is + \item{\code{alt(x)}, \code{alt(x) <- value}:}{ + Gets or sets the alternate allele data (ALT). When \code{x} is a CollapsedVCF, \code{value} must be a \code{DNAStringSetList} or \code{CompressedCharacterList}. For ExpandedVCF, \code{value} must be a \code{DNAStringSet} or \code{character}. } - \item{\code{qual(x)}, \code{qual(x) <- value}: - Returns or sets the quality scores (QUAL). \code{value} must + \item{\code{qual(x)}, \code{qual(x) <- value}:}{ + Returns or sets the quality scores (QUAL). \code{value} must be an \code{numeric(1L)}. } - \item{\code{filt(x)}, \code{filt(x) <- value}: - Returns or sets the filter data. \code{value} must + \item{\code{filt(x)}, \code{filt(x) <- value}:}{ + Returns or sets the filter data. \code{value} must be a \code{character(1L)}. Names must be one of 'REF', 'ALT', 'QUAL' or 'FILTER'. } } } - \item{}{ - \code{mcols(x)}, \code{mcols(x) <- value}: - These methods behave the same as \code{mcols(rowRanges(x))} and - \code{mcols(rowRanges(x)) <- value}. This method does not manage the - fixed fields, 'REF', 'ALT', 'QUAL' or 'FILTER'. To modify those - columns use \code{fixed<-}. + \item{\code{mcols(x)}, \code{mcols(x) <- value}}{ + These methods behave the same as \code{mcols(rowRanges(x))} and + \code{mcols(rowRanges(x)) <- value}. This method does not manage the + fixed fields, 'REF', 'ALT', 'QUAL' or 'FILTER'. To modify those + columns use \code{fixed<-}. } - \item{}{ - \code{fixed(x)}, \code{fixed(x) <- value}: - Gets or sets a DataFrame of REF, ALT, QUAL and FILTER only. - Note these fields are displayed as metadata columns with - the rowRanges() data (set to fixed = FALSE to suppress). + \item{\code{fixed(x)}, \code{fixed(x) <- value}}{ + Gets or sets a DataFrame of REF, ALT, QUAL and FILTER only. + Note these fields are displayed as metadata columns with + the rowRanges() data (set to fixed = FALSE to suppress). } - \item{}{ - \code{info(x, ..., row.names = TRUE)}, \code{info(x) <- value}: - Gets or sets a DataFrame of INFO variables. Row names are added - if unique and \code{row.names=TRUE}. + \item{\code{info(x, ..., row.names = TRUE)}, \code{info(x) <- value}}{ + Gets or sets a DataFrame of INFO variables. Row names are added + if unique and \code{row.names=TRUE}. } - \item{}{ - \code{geno(x, withDimnames=TRUE)}, \code{geno(x) <- value}: - oets a SimpleList of genotype data. - \code{value} is a SimpleList. To replace a single variable in - the SimpleList use \code{geno(x)$variable <- value}; in this - case \code{value} must be a matrix or array. By default - row names are returned; to override specify - \code{geno(vcf, withDimnames=FALSE)}. + \item{\code{geno(x, withDimnames=TRUE)}, \code{geno(x) <- value}}{ + Gets a SimpleList of genotype data. + \code{value} is a SimpleList. To replace a single variable in + the SimpleList use \code{geno(x)$variable <- value}; in this + case \code{value} must be a matrix or array. By default + row names are returned; to override specify + \code{geno(vcf, withDimnames=FALSE)}. } - \item{}{ - \code{metadata(x)}: - Gets a \code{list} of experiment-related data. By default this - list includes the \sQuote{header} information from the VCF file. - See the use of \code{header()} for details in extracting - header information. + \item{\code{metadata(x)}}{ + Gets a \code{list} of experiment-related data. By default this + list includes the \sQuote{header} information from the VCF file. + See the use of \code{header()} for details in extracting + header information. } - \item{}{ - \code{colData(x)}, \code{colData(x) <- value}: - Gets or sets a \code{DataFrame} of sample-specific information. Each row - represents a sample in the VCF file. \code{value} must be a - \code{DataFrame} with rownames representing the samples in the VCF + \item{\code{colData(x)}, \code{colData(x) <- value}}{ + Gets or sets a \code{DataFrame} of sample-specific information. Each row + represents a sample in the VCF file. \code{value} must be a + \code{DataFrame} with rownames representing the samples in the VCF file. } - \item{}{ - \code{genome(x)}: + \item{\code{genome(x)}}{ Extract the \code{genome} information from the \code{GRanges} object returned by the \code{rowRanges} accessor. } - \item{}{ - \code{seqlevels(x)}: + \item{\code{seqlevels(x)}}{ Extract the \code{seqlevels} from the \code{GRanges} object returned by the \code{rowRanges} accessor. } - \item{}{ - \code{strand(x)}: + \item{\code{strand(x)}}{ Extract the \code{strand} from the \code{GRanges} object returned by the \code{rowRanges} accessor. } - \item{}{ - \code{header(x)}, \code{header(x)<- value}: + \item{\code{header(x)}, \code{header(x)<- value}}{ Get or set the VCF header information. Replacement value - must be a \code{VCFHeader} object. To modify individual elements - use \code{info<-}, \code{geno<-} or \code{meta<-} on a + must be a \code{VCFHeader} object. To modify individual elements + use \code{info<-}, \code{geno<-} or \code{meta<-} on a \sQuote{VCFHeader} object. See ?\code{VCFHeader} man page for details. - \itemize{ - \item{\code{info(header(x))}} - \item{\code{geno(header(x))}} - \item{\code{meta(header(x))}} - \item{\code{samples(header(x))}} + \itemize{ + \item \code{info(header(x))} + \item \code{geno(header(x))} + \item \code{meta(header(x))} + \item \code{samples(header(x))} } } - \item{}{\code{vcfFields(x)} + \item{\code{vcfFields(x)}}{ Returns a \code{\link[IRanges]{CharacterList}} of all available VCF fields, with names of \code{fixed}, \code{info}, \code{geno} and \code{samples} indicating the four categories. Each element is a - character() vector of available VCF field names within each category. + character() vector of available VCF field names within each category. } } } @@ -251,21 +239,21 @@ In the following code \code{x} is a VCF object, and \dots is a list of VCF objects. \describe{ - \item{}{ - \code{x[i, j]}, \code{x[i, j] <- value}: Gets or sets rows and columns. + \item{\code{x[i, j]}, \code{x[i, j] <- value}}{ + Gets or sets rows and columns. \code{i} and \code{j} can be integer or logical vectors. \code{value} is a replacement \code{VCF} object. } - \item{}{ - \code{subset(x, subset, select, ...)}: Restricts \code{x} by + \item{\code{subset(x, subset, select, ...)}}{ + Restricts \code{x} by evaluating the \code{subset} argument in the scope of \code{rowData(x)} and \code{info(x)}, and \code{select} in the context of \code{colData(x)}. The \code{subset} argument restricts by rows, while the \code{select} argument restricts by column. The \code{\dots} are passed to the underlying \code{subset()} calls. } - \item{}{ - \code{cbind(...)}, \code{rbind(...)}: \code{cbind} combines objects with + \item{\code{cbind(...)}, \code{rbind(...)}}{ + \code{cbind} combines objects with identical ranges (\code{rowRanges}) but different samples (columns in \code{assays}). The colnames in \code{colData} must match or an error is thrown. Columns with duplicate names in \code{fixed}, \code{info} and @@ -276,7 +264,7 @@ in \code{colData} must contain the same data. The \sQuote{Samples} columns in \code{colData} (created by \code{readVcf}) are renamed with a numeric extension ordered as they were input to \code{rbind} e.g., - \dQuote{Samples.1, Samples.2, ...} etc. + \dQuote{Samples.1, Samples.2, ...} etc. \code{metadata} from all objects are combined into a \code{list} with no name checking. @@ -288,18 +276,17 @@ \section{expand}{ In the following code snippets \code{x} is a CollapsedVCF object. \describe{ - \item{}{ - \code{expand(x, ..., row.names = FALSE)}: - Expand (unlist) the ALT column of a CollapsedVCF object to one row + \item{\code{expand(x, ..., row.names = FALSE)}}{ + Expand (unlist) the ALT column of a CollapsedVCF object to one row per ALT value. Variables with Number='A' have one value per alternate - allele and are expanded accordingly. The 'AD' genotype field + allele and are expanded accordingly. The 'AD' genotype field (and any variables with 'Number' set to 'R') is expanded into REF/ALT pairs. For all other fields, the rows are replicated to match the elementNROWS of ALT. - The output is an ExpandedVCF with ALT as a \code{DNAStringSet} + The output is an ExpandedVCF with ALT as a \code{DNAStringSet} or \code{character} (structural variants). By default rownames - are NULL. When \code{row.names=TRUE} the expanded output has + are NULL. When \code{row.names=TRUE} the expanded output has duplicated rownames corresponding to the original \code{x}. } } diff --git a/man/VCFHeader-class.Rd b/man/VCFHeader-class.Rd index 6fe4c34..52ba814 100644 --- a/man/VCFHeader-class.Rd +++ b/man/VCFHeader-class.Rd @@ -44,8 +44,8 @@ \section{Constructor}{ \describe{ - \item{}{ - \code{VCFHeader(reference = character(), samples = character(), + \item{\code{VCFHeader}}{ + \code{VCFHeader(reference = character(), samples = character(), header = DataFrameList(), ...) } } @@ -55,66 +55,59 @@ \section{Accessors}{ In the following code snippets \code{x} is a VCFHeader object. \describe{ - \item{}{ - \code{samples(x)}: - Returns a character() vector of names of samples. + \item{\code{samples(x)}}{ + Returns a character() vector of names of samples. } - \item{}{ - \code{header(x)}: + \item{\code{header(x)}}{ Returns all information in the header slot which includes \code{meta}, \code{info} and \code{geno} if present. } - \item{}{ - \code{meta(x)}, \code{meta(x)<- value}: The getter returns a + \item{\code{meta(x)}, \code{meta(x)<- value}}{ + The getter returns a \code{DataFrameList}. Each \code{DataFrame} represents a unique "key" name in the header file. Multiple header lines with the same "key" are parsed into the same \code{DataFrame} with the "ID" field as the row names. Simple header lines have no "ID" field in which case the "key" is used as the row name. - + NOTE: In VariantAnnotation <= 1.27.5, the \code{meta()} extractor returned a \code{DataFrame} called "META" which held all simple key-value header lines. The VCF 4.3 specs allowed headers lines with key name "META" which caused a name clash with the pre-existing - "META" \code{DataFrame}. + "META" \code{DataFrame}. In \code{VariantAnnotation} >=1.27.6 the "META" \code{DataFrame} was split and each row became its own separate \code{DataFrame}. Calling \code{meta()} on a \code{VCFHeader} object now returns a list of \code{DataFrames}, one for each unique key name in the header. } - \item{}{ - \code{fixed(x), fixed(x)<- value}: + \item{\code{fixed(x)}, \code{fixed(x)<- value}}{ Returns a \code{DataFrameList} of information pertaining to any of - \sQuote{REF}, \sQuote{ALT}, \sQuote{FILTER} and \sQuote{QUAL}. + \sQuote{REF}, \sQuote{ALT}, \sQuote{FILTER} and \sQuote{QUAL}. Replacement value must be a \code{DataFrameList} with one or more of - the following names, \sQuote{QUAL}, \sQuote{FILTER}, \sQuote{REF} - and \sQuote{ALT}. + the following names, \sQuote{QUAL}, \sQuote{FILTER}, \sQuote{REF} + and \sQuote{ALT}. } - \item{}{ - \code{info(x)}, \code{info(x)<- value}: + \item{\code{info(x)}, \code{info(x)<- value}}{ Gets or sets a \code{DataFrame} of \sQuote{INFO} information. Replacement value must be a \code{DataFrame} with 3 columns - named \sQuote{Number}, \sQuote{Type} and \sQuote{Description}. + named \sQuote{Number}, \sQuote{Type} and \sQuote{Description}. } - \item{}{ - \code{geno(x)}, \code{geno(x)<- value}: + \item{\code{geno(x)}, \code{geno(x)<- value}}{ Returns a \code{DataFrame} of \sQuote{FORMAT} information. Replacement value must be a \code{DataFrame} with 3 columns - named \sQuote{Number}, \sQuote{Type} and \sQuote{Description}. + named \sQuote{Number}, \sQuote{Type} and \sQuote{Description}. } - \item{}{ - \code{reference(x)}: + \item{\code{reference(x)}}{ Returns a character() vector with names of reference sequences. Not relevant for \code{scanVcfHeader}. } - \item{}{ - \code{vcfFields(x)}: + \item{\code{vcfFields(x)}}{ Returns a \code{\link[IRanges]{CharacterList}} of all available VCF fields, with names of \code{fixed}, \code{info}, \code{geno} and \code{samples} indicating the four categories. Each element is a - character() vector of available VCF field names within each category. + character() vector of available VCF field names within each category. } } } diff --git a/man/VRanges-class.Rd b/man/VRanges-class.Rd index 57e6866..d158627 100644 --- a/man/VRanges-class.Rd +++ b/man/VRanges-class.Rd @@ -143,11 +143,11 @@ \section{Constructors}{ \describe{ - \item{}{ - \code{VRanges(seqnames = Rle(), ranges = IRanges(), ref = character(), - alt = NA_character_, totalDepth = NA_integer_, refDepth = NA_integer_, - altDepth = NA_integer_, ..., sampleNames = NA_character_, - softFilterMatrix = FilterMatrix(matrix(nrow = length(gr), + \item{\code{VRanges(...)}}{ + \code{VRanges(seqnames = Rle(), ranges = IRanges(), ref = character(), + alt = NA_character_, totalDepth = NA_integer_, refDepth = NA_integer_, + altDepth = NA_integer_, ..., sampleNames = NA_character_, + softFilterMatrix = FilterMatrix(matrix(nrow = length(gr), ncol = 0L), FilterRules()), hardFilters = FilterRules())}: Creates a VRanges object. \describe{ @@ -176,7 +176,7 @@ subset the object to its current state.} } } - \item{}{ + \item{\code{makeVRangesFromGRanges(...)}}{ \code{makeVRangesFromGRanges(gr, ref.field="ref", alt.field="alt", @@ -229,7 +229,7 @@ These functions/methods coerce objects to and from \code{VRanges}: \describe{ - \item{}{ + \item{\code{asVCF(x, info, filter, meta)}}{ \code{asVCF(x, info = character(), filter = character(), meta = character())}: Creates a VCF object from a VRanges object. The following gives the mapping from VRanges components to VCF: @@ -263,18 +263,17 @@ logical column with the reverse coercion. There are many other cases of irreversibility. } - \item{}{ - \code{as(from, "VCF")}: Like calling \code{asVCF(from)}. + \item{\code{as(from, "VCF")}}{ + Like calling \code{asVCF(from)}. } - \item{}{ - \code{as(from, "VRanges")}: + \item{\code{as(from, "VRanges")}}{ When \code{from} is a \code{VCF} this coercion is essentially the inverse of \code{asVCF}. Information missing in the VCF is imputed as NA. When \code{from} is a \code{GRanges}, metadata columns of \code{ref}, \code{alt}, \code{refDepth}, \code{altDepth}, - \code{totalDepth} and \code{sampleNames} are transfered to + \code{totalDepth} and \code{sampleNames} are transfered to the \code{VRanges} object. Additional metadata columns in the \code{GRanges} can be retained or dropped with \code{keep.extra.columns}. See also \code{makeVRangesFromGRanges}. @@ -287,76 +286,70 @@ provides the following, where \code{x} is a VRanges object. \describe{ - \item{}{ - \code{alt(x), alt(x) <- value}: Get or set the alt allele (character). + \item{\code{alt(x)}, \code{alt(x) <- value}}{ + Get or set the alt allele (character). } - \item{}{ - \code{ref(x), ref(x) <- value}: Get or set the ref allele (character). + \item{\code{ref(x)}, \code{ref(x) <- value}}{ + Get or set the ref allele (character). } - \item{}{ - \code{altDepth(x), altDepth(x) <- value}: Get or set the alt allele - read depth (integer). + \item{\code{altDepth(x)}, \code{altDepth(x) <- value}}{ + Get or set the alt allele read depth (integer). } - \item{}{ - \code{refDepth(x), refDepth(x) <- value}: Get or set the ref - allele read depth (integer). + \item{\code{refDepth(x)}, \code{refDepth(x) <- value}}{ + Get or set the ref allele read depth (integer). } - \item{}{ - \code{totalDepth(x), totalDepth(x) <- value}: Get or set the total - read depth (integer). + \item{\code{totalDepth(x)}, \code{totalDepth(x) <- value}}{ + Get or set the total read depth (integer). } - \item{}{ - \code{altFraction(x)}: Returns \code{altDepth(x)/totalDepth(x)} (numeric). + \item{\code{altFraction(x)}}{ + Returns \code{altDepth(x)/totalDepth(x)} (numeric). } - \item{}{ - \code{sampleNames(x), sampleNames(x) <- value}: Get or set the - sample names (character/factor). + \item{\code{sampleNames(x)}, \code{sampleNames(x) <- value}}{ + Get or set the sample names (character/factor). } - \item{}{ - \code{softFilterMatrix(x), softFilterMatrix(x) <- value}: Gets or - sets the soft filter matrix (any matrix, but ideally a + \item{\code{softFilterMatrix(x)}, \code{softFilterMatrix(x) <- value}}{ + Gets or sets the soft filter matrix (any matrix, but ideally a \code{FilterMatrix}). } - \item{}{ - \code{resetFilter(x)}: Removes all columns from \code{softFilterMatrix}. + \item{\code{resetFilter(x)}}{ + Removes all columns from \code{softFilterMatrix}. } - \item{}{ - \code{called(x)}: Returns whether all filter results in + \item{\code{called(x)}}{ + Returns whether all filter results in \code{softFilterMatrix(x)} are \code{TRUE} for each variant. } - \item{}{ - \code{hardFilters(x), hardFilters(x) <- value}: Gets or - sets the hard filters (those applied to yield the current subset). + \item{\code{hardFilters(x)}, \code{hardFilters(x) <- value}}{ + Gets or sets the hard filters (those applied to yield the current subset). } } } \section{Utilities and Conveniences}{ \describe{ - \item{}{ - \code{match(x)}: Like GRanges \code{match}, except matches on the + \item{\code{match(x)}}{ + Like GRanges \code{match}, except matches on the combination of chromosome, start, width, and \strong{alt}. } - \item{}{ - \code{tabulate(bin)}: Finds \code{unique(bin)} and counts how many + \item{\code{tabulate(bin)}}{ + Finds \code{unique(bin)} and counts how many times each unique element occurs in \code{bin}. The result is stored in \code{mcols(bin)$sample.count}. } - \item{}{ - \code{softFilter(x, filters, ...)}: applies the \code{FilterRules} + \item{\code{softFilter(x, filters, ...)}}{ + Applies the \code{FilterRules} in \code{filters} to \code{x}, storing the results in \code{softFilterMatrix}. } - } + } } \section{Input/Output to/from VCF}{ \describe{ - \item{}{ - \code{writeVcf(obj, filename, ...)}: coerces to a VCF object and + \item{\code{writeVcf(obj, filename, ...)}}{ + Coerces to a VCF object and writes it to a file; see \code{\link{writeVcf}}. } - \item{}{ + \item{\code{readVcfAsVRanges(x, genome, param, ...)}}{ \code{readVcfAsVRanges(x, genome, param = ScanVcfParam(), ...)}: Reads a VCF \code{x} directly into a \code{VRanges}; see \code{\link{readVcf}} for details on the arguments. diff --git a/man/VRangesList-class.Rd b/man/VRangesList-class.Rd index f3633ac..25194bf 100644 --- a/man/VRangesList-class.Rd +++ b/man/VRangesList-class.Rd @@ -32,8 +32,7 @@ \section{Constructor}{ \describe{ - \item{}{ - \code{VRangesList(...)}: + \item{\code{VRangesList(...)}}{ Creates a VRangesList object from \code{VRanges} objects in \dots. } } @@ -41,12 +40,11 @@ \section{Accessors}{ \describe{ - \item{}{ - \code{alt(x)}: Returns a CharacterList or RleList, effectively by + \item{\code{alt(x)}}{ + Returns a CharacterList or RleList, effectively by calling \code{alt(x[[i]])} on each element of \code{x}. } - \item{}{ - \code{ref(x)}: + \item{\code{ref(x)}}{ Returns a CharacterList, effectively by calling \code{ref(x[[i]])} on each element of \code{x}. } @@ -55,8 +53,8 @@ \section{Utilities}{ \describe{ - \item{}{ - \code{stackSamples(x)}: Concentrates the elements in \code{x}, + \item{\code{stackSamples(x)}}{ + Concentrates the elements in \code{x}, using \code{names(x)} to appropriately fill \code{sampleNames} in the result. } diff --git a/man/VariantType-class.Rd b/man/VariantType-class.Rd index 9e402a2..4ccdac1 100644 --- a/man/VariantType-class.Rd +++ b/man/VariantType-class.Rd @@ -131,30 +131,25 @@ In the following code, \code{x} is a \code{PromoterVariants} or a \code{AllVariants} object. \describe{ - \item{}{ - \code{upstream(x)}, \code{upstream(x) <- value}: + \item{\code{upstream(x)}, \code{upstream(x) <- value}}{ Gets or sets the number of base pairs defining a range upstream of the 5' end (excludes 5' start value). } - \item{}{ - \code{downstream(x)}, \code{downstream(x) <- value}: + \item{\code{downstream(x)}, \code{downstream(x) <- value}}{ Gets or sets the number of base pairs defining a range downstream of the 3' end (excludes 3' end value). } - \item{}{ - \code{idType(x)}, \code{idType(x) <- value}: - Gets or sets the \code{character()} which controls the id returned + \item{\code{idType(x)}, \code{idType(x) <- value}}{ + Gets or sets the \code{character()} which controls the id returned in the PRECEDEID and FOLLOWID output columns. Possible values are "gene" and "tx". } - \item{}{ - \code{promoters(x)}, \code{promoters(x) <- value}: - Gets or sets the \code{PromoterVariants} in the + \item{\code{promoters(x)}, \code{promoters(x) <- value}}{ + Gets or sets the \code{PromoterVariants} in the \code{AllVariants} object. } - \item{}{ - \code{intergenic(x)}, \code{intergenic(x) <- value}: - Gets or sets the \code{IntergenicVariants} in the + \item{\code{intergenic(x)}, \code{intergenic(x) <- value}}{ + Gets or sets the \code{IntergenicVariants} in the \code{AllVariants} object. } } diff --git a/man/VcfFile-class.Rd b/man/VcfFile-class.Rd index b579ab3..af629a6 100644 --- a/man/VcfFile-class.Rd +++ b/man/VcfFile-class.Rd @@ -28,50 +28,50 @@ ## Constructors \describe{ - \item{}{ + \item{VcfFile}{ VcfFile(file, index = paste(file, "tbi", sep="."), ..., yieldSize=NA_integer_) } - \item{}{ + \item{VcfFileList}{ VcfFileList(..., yieldSize=NA_integer_) } } - + ## Accessors \describe{ - \item{}{ + \item{index}{ index(object)} - \item{}{ + \item{path}{ path(object, ...)} - \item{}{ + \item{isOpen}{ isOpen(con, rw="")} - \item{}{ + \item{yieldSize}{ yieldSize(object, ...)} - \item{}{ + \item{yieldSize<-}{ yieldSize(object, ...) <- value} - \item{}{ + \item{show}{ show(object) } } - + ## Opening / closing \describe{ - \item{}{ + \item{open}{ open(con, ...)} - \item{}{ + \item{close}{ close(con, ...)} } - + ## method \describe{ - \item{}{ + \item{vcfFields}{ vcfFields(object) } } } \section{arguments}{ - \itemize{ + \describe{ \item{con}{An instance of \code{VcfFile}.} \item{file}{A character(1) vector to the Vcf file diff --git a/man/isSNV-methods.Rd b/man/isSNV-methods.Rd index 137a22f..022104c 100644 --- a/man/isSNV-methods.Rd +++ b/man/isSNV-methods.Rd @@ -96,19 +96,19 @@ All functions return a logical vector the length of \code{x}. Variants in gvcf files with NON_REF alt alleles return TRUE; structural variants return FALSE. - \itemize{ + \describe{ \item{isSNV: }{ Reference and alternate alleles are both a single nucleotide long. } \item{isInsertion: }{ - Reference allele is a single nucleotide and the alternate allele + Reference allele is a single nucleotide and the alternate allele is greater (longer) than a single nucleotide and the first - nucleotide of the alternate allele matches the reference. + nucleotide of the alternate allele matches the reference. } \item{isDeletion: }{ - Alternate allele is a single nucleotide and the reference allele + Alternate allele is a single nucleotide and the reference allele is greater (longer) than a single nucleotide and the first - nucleotide of the reference allele matches the alternate. + nucleotide of the reference allele matches the alternate. } \item{isIndel: }{ The variant is either a deletion or insertion as determined @@ -124,7 +124,7 @@ } \item{isTransition: }{ Reference and alternate alleles are both a single nucleotide long. - The reference-alternate pair interchange is of either two-ring + The reference-alternate pair interchange is of either two-ring purines (A <-> G) or one-ring pyrimidines (C <-> T). } } diff --git a/man/readVcf-methods.Rd b/man/readVcf-methods.Rd index 2058d65..09a9648 100644 --- a/man/readVcf-methods.Rd +++ b/man/readVcf-methods.Rd @@ -60,20 +60,20 @@ readGT(file, nucleotides=FALSE, param=ScanVcfParam(), ..., row.names=TRUE) and ?\code{indexVcf} for help creating a \code{\link{VcfFile}}. } \item{genome}{A \code{character} or \code{Seqinfo} object. - \itemize{ - \item{\code{character}:}{ Genome identifier as a single string or named - character vector. Names of the character vector correspond to - chromosome names in the file. This identifier replaces the genome + \describe{ + \item{\code{character}:}{ Genome identifier as a single string or named + character vector. Names of the character vector correspond to + chromosome names in the file. This identifier replaces the genome information in the VCF \code{Seqinfo} (i.e., \code{seqinfo(vcf)}). When not provided, \code{genome} is taken from the VCF file header. } \item{\code{Seqinfo}:}{ When \code{genome} is provided as a \code{Seqinfo} - it is propagated to the VCF output. If seqinfo information can be - obtained from the file, + it is propagated to the VCF output. If seqinfo information can be + obtained from the file, (i.e., seqinfo(scanVcfHeader(fl)) is not empty), the output \code{Seqinfo} is a product of merging the two. - If a param (i.e., ScanVcfParam) is used in the call to \code{readVcf}, + If a param (i.e., ScanVcfParam) is used in the call to \code{readVcf}, the seqlevels of the param ranges must be present in \code{genome}. } } diff --git a/man/summarizeVariants-methods.Rd b/man/summarizeVariants-methods.Rd index dad1051..35ee9ed 100644 --- a/man/summarizeVariants-methods.Rd +++ b/man/summarizeVariants-methods.Rd @@ -71,12 +71,12 @@ be transcripts-by-sample. If the \code{GRangesList} is genes, the count matrix will be gene-by-sample. - \itemize{ + \describe{ \item{Counting with locateVariants() :}{ Variant counts are always summarized transcript-by-sample. - When \code{query} is a \code{GRangesList}, it must be compatible - with the \code{VariantType}-class given as the \code{mode} argument. + When \code{query} is a \code{GRangesList}, it must be compatible + with the \code{VariantType}-class given as the \code{mode} argument. The list below specifies the appropriate \code{GRangesList} for each \code{mode}. \describe{ @@ -88,17 +88,17 @@ \item{PromoterVariants :}{list of transcripts} } - When \code{query} is a \code{TxDb}, the appropriate - region-by-transcript \code{GRangesList} listed above is extracted - internally and used as the annotation. + When \code{query} is a \code{TxDb}, the appropriate + region-by-transcript \code{GRangesList} listed above is extracted + internally and used as the annotation. } - + \item{Counting with a user-supplied function :}{ \code{subject} must be a \code{GRangesList} and \code{mode} must be the name of a function. The count function must take 'query' - and 'subject' arguments and return a \code{Hits} object. Counts are + and 'subject' arguments and return a \code{Hits} object. Counts are summarized by the outer list elements of the \code{GRangesList}. } } From e9748a2da7da6ddc5008f555efd84b9f0bfdb93b Mon Sep 17 00:00:00 2001 From: vjcitn Date: Fri, 17 Jul 2026 21:17:48 -0400 Subject: [PATCH 2/3] bumping version corresponding to Rd changes --- DESCRIPTION | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DESCRIPTION b/DESCRIPTION index 9bdc489..b92760a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -3,7 +3,7 @@ Type: Package Title: Annotation of Genetic Variants Description: Annotate variants, compute amino acid coding changes, predict coding outcomes. -Version: 1.59.0 +Version: 1.59.2 Authors@R: c( person("Valerie", "Oberchain", role="aut"), person("Martin", "Morgan", role="aut"), From bb6ce150e9988216b57611f224d465febabb38df Mon Sep 17 00:00:00 2001 From: John Muirhead-Gould Date: Mon, 6 Jul 2026 20:31:28 -0400 Subject: [PATCH 3/3] fix: handle non-BGZF gzip VCFs (e.g. bcftools -Oz) in readVcf (closes #32) Regular gzip files (.vcf.gz compressed with gzip/bcftools -Oz) are valid gzip but NOT BGZF, so htslib/Rsamtools rejects them with a confusing error. Fix: add .is_bgzf() (reads 18-byte header, checks the BC extra subfield), .ungzip_vcf() (decompresses to a temp plain VCF), and .prepareFile() which is called by both character readVcf methods before .checkFile(). The temp file is registered with on.exit() in the caller frame so it is cleaned up automatically after readVcf returns. BGZF files, plain .vcf files, and TabixFile inputs are unaffected. --- R/methods-readVcf.R | 63 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/R/methods-readVcf.R b/R/methods-readVcf.R index c78670e..6ce4a96 100644 --- a/R/methods-readVcf.R +++ b/R/methods-readVcf.R @@ -43,6 +43,9 @@ setMethod(readVcf, c(file="TabixFile", param="missing"), setMethod(readVcf, c(file="character", param="ANY"), function(file, genome, param, ..., row.names=TRUE) { + file <- .prepareFile(file) + if (!is.null(attr(file, "tmpfile"))) + on.exit(unlink(attr(file, "tmpfile")), add=TRUE) file <- .checkFile(file) .readVcf(file, genome, param, row.names=row.names, ...) }) @@ -50,11 +53,71 @@ setMethod(readVcf, c(file="character", param="ANY"), setMethod(readVcf, c(file="character", param="missing"), function(file, genome, param, ..., row.names=TRUE) { + file <- .prepareFile(file) + if (!is.null(attr(file, "tmpfile"))) + on.exit(unlink(attr(file, "tmpfile")), add=TRUE) file <- .checkFile(file) .readVcf(file, genome, param=ScanVcfParam(), row.names=row.names, ...) }) +## Detect whether a file path points to a BGZF-compressed file. +## BGZF is a specialisation of gzip: the first block has the 2-byte extra +## subfield ID "BC" at byte positions 13-14 (1-based). Regular gzip +## (e.g. produced by bcftools -Oz) passes the is-gzip test but NOT the +## BC-subfield test, so Rsamtools / htslib cannot index or read them. +.is_bgzf <- function(path) { + raw_bytes <- tryCatch( + readBin(path, "raw", n = 18L), + error = function(e) raw(0) + ) + if (length(raw_bytes) < 18L) + return(FALSE) + ## gzip magic (bytes 1-2) + FLG byte has FEXTRA bit (0x04) set (byte 4) + is_gzip <- raw_bytes[1L] == as.raw(0x1f) && + raw_bytes[2L] == as.raw(0x8b) + has_fextra <- bitwAnd(as.integer(raw_bytes[4L]), 4L) == 4L + ## BGZF extra subfield ID "BC" at byte positions 13-14 + is_bgzf <- is_gzip && has_fextra && + raw_bytes[13L] == as.raw(0x42) && # 'B' + raw_bytes[14L] == as.raw(0x43) # 'C' + is_bgzf +} + +## Decompress a regular-gzip VCF (e.g. bcftools -Oz output) to a temp plain +## VCF file. Returns the path to the temp file; caller is responsible for +## unlinking it. +.ungzip_vcf <- function(path) { + tmp <- tempfile(fileext = ".vcf") + con_in <- gzcon(file(path, open = "rb")) + lines <- readLines(con_in) + close(con_in) + writeLines(lines, tmp) + tmp +} + +.prepareFile <- function(x) +{ + ## If file looks like gzip but is NOT BGZF (e.g. produced by bcftools -Oz + ## or plain `gzip`), Rsamtools/htslib cannot handle it. Decompress to a + ## temporary plain-text VCF. We tag the path with a "tmpfile" attribute + ## so the *caller* can register on.exit(unlink(...)) in its own frame, + ## ensuring the file lives for the full duration of the readVcf call. + is_gz <- grepl("\\.(gz|bgz)$", x, ignore.case = TRUE) + if (is_gz && !.is_bgzf(x)) { + message("Note: '", basename(x), "' appears to be gzip- (not BGZF-) ", + "compressed.\n", + " Decompressing to a temporary file for reading. ", + "For faster repeated access\n", + " consider re-compressing with Rsamtools::bgzip() and ", + "indexing with indexVcf().") + tmp <- .ungzip_vcf(x) + attr(tmp, "tmpfile") <- tmp # signal caller to clean up + return(tmp) + } + x +} + .checkFile <- function(x) { if (1L != length(x))