NEWS.md
mesaDimRed, mesaPCA and mesaUMAP objects are now checked for internal consistency, and validObject() rejects an inconsistent one with a message naming the problem: duplicate or missing windows, results without sample IDs, mixed PCA and UMAP results, results covering different samples, or samples absent from sampleTable or dataTable. (#115, PR #149)getSampleNames() now works on mesaDimRed objects and returns the sample IDs their results cover (sample group names with useGroupMeans = TRUE). (#10, PR #149)mesaDimRed, mesaPCA and mesaUMAP objects without @: getResults(), getParameters(), getCoordinates(), getPrcomp(), getWindowNames(), getDataTable(), getSampleTable() and getSampleNames(). On a mesaDimRed, getResults(), getCoordinates(), getPrcomp() and getWindowNames() return a list with one element per result. getCoordinates(), getWindowNames() and getSampleNames() also work directly on mesaPCA and mesaUMAP objects, and getPrcomp() on mesaPCA objects. The first argument of getDataTable() is now x instead of qseaSet. (#117, PR #158)as.data.frame() can now be applied to mesaDimRed objects, returning one table of coordinates and sample annotations for all PCA or UMAP results in the object. (#117, PR #158)getWindowNames() now says “Unknown data type” when given something that is not a qseaSet, mesaDimRed, mesaPCA, mesaUMAP, GRanges or window table. (#117, PR #158)plotPCA() and plotUMAP() no longer fail when the sampleTable has a column named like a component (for example PC1); the plot uses the computed coordinates. (#117, PR #158)plotPCA() and plotUMAP() now say that params$method must be "PCA" or "UMAP" when a mesaDimRed has none, instead of failing with “argument is of length zero”. (#117, PR #158)mesaDimRed validity now checks sample IDs against the sampleTable$sample_name column, as qsea does, rather than its row names, and says so when the column is missing. (#117, PR #158)mesaDimRed objects no longer have a samples slot, and mesaDimRed() no longer takes a samples argument. Code that reads @samples should call getSampleNames() instead, and code that passes samples = to mesaDimRed() should drop it; objects saved with an earlier version still load and work. (#10, PR #149)NEWS.md bullet now ends with the issue and the pull request that delivered it, for example ([#162](https://github.com/cruk-mi/mesa/issues/162), [PR #165](https://github.com/cruk-mi/mesa/pull/165)).mesaDimRed, mesaPCA and mesaUMAP help pages list their accessors, ?dimRedAccessors documents them, and the PCA vignette shows how to read a getPCA() result. (#7, PR #158)exampleTumourNormal, links to the pkgdown site and vignettes, and citations. (PR #108)citation("mesa") now returns the two published papers. (PR #108)data-raw/figures/. (PR #110)?mesa is now a user-facing overview listed in the reference index: what enrichment sequencing measures, the workflow from makeQset() to annotateWindows(), the example datasets and the vignettes. (#118, PR #151)addBamCoveragePairedAndUnpaired(), addMedipsEnrichmentFactors(), addNormalisation(), annotateWindows(), getGenomicFeatureDistribution(), getMesaAnnoDb(), getMesaGenome(), getMesaTxDb(), makeQset(), plotGenomicFeatureDistribution(), plotRegionsHeatmap(), runHMMCopy(), summariseDMRsByGene(), exampleMouse and exampleTumourNormal. Examples that need MEDIPSData or the annotation packages are skipped when those are not installed. (#118, PR #151)addMedipsEnrichmentFactors() example works: it adds coverage before calculating the enrichment factors, instead of failing. (#118, PR #151)makeQset() argument properPairsOnly and CNVmethod = "None", the group1/group2 contrast columns of calculateDMRs(), and describe the blind calibration and getBetaTable(useGroupMeans = TRUE) output correctly. (#120, PR #155)?addHyperStableFraction and ?hg38UltraStableProbes now links to its DOI instead of PubMed. (PR #155)main; Codecov statuses are informational. (PR #108)immunedeconv (with its GitHub dependencies) or imsig, which mesa does not use, and takes ggtree from Bioconductor instead of a GitHub pin. It now installs nothing from GitHub, so it no longer needs the pinned archives and SHA check added in 0.99.7. (PR #132)vX.Y.Z tag now publishes a GitHub Release with the source tarball and that version’s NEWS.md notes, once the tag matches DESCRIPTION and NEWS.md and passes the r-universe Bioconductor build. (PR #112)R CMD check. A push to an open pull request no longer starts a second run, and cancels the superseded one. (PR #114)calculateCGEnrichment() no longer depends on MEDIPS: reads are imported with Rsamtools and CpGs located with Biostrings. This fixes a crash in a fresh session (could not find function "strand<-") and silent read loss on chromosomes longer than 2^29 bp. Read counts are otherwise unchanged. (#81, PR #102)calculateCGEnrichment() now errors on a chr.select entry absent from the BSgenome instead of returning no reads. (PR #102)uniq now accepts only 0 (keep all reads) or 1 (one read per location); the unused p-value form is removed. (PR #102)chr.select = NULL, CpGs are located only on chromosomes that carry reads, which is much faster on genomes with many scaffolds (e.g. hg19). (PR #102)MEDIPS removed from Suggests. (PR #102)Config/roxygen2/version in DESCRIPTION; the devcontainer installs that exact version. Regenerated man/ and NAMESPACE with roxygen2 8.1.0 (link anchors and importFrom() formatting only). (PR #105)roxygen-drift CI job that fails when man/ or NAMESPACE is out of sync with the roxygen comments in R/. (PR #105)GenomicAlignments::cigarWidthAlongReferenceSpace() with cigarillo::cigar_extent_along_ref(), fixing the vignette build on Bioconductor devel (GenomicAlignments >= 1.49.1). (PR #98)≥, ≤, ∈) with ASCII equivalents (>=, <=, in) in roxygen2 comments and .Rd files to fix LaTeX errors in the PDF manual. (PR #88)summariseDMRsByGene() example in \donttest{} to keep R CMD check within the 10-minute limit (~52 s saved). (PR #88)bioconductor/bioconductor_docker, dropping conda; devcontainer and CI now share the same toolchain. The R (>=) line in DESCRIPTION is the single source of truth: Bioc version and image tag are derived automatically; upgrading R requires editing that one line only. (PR #92)GPL-3 to GPL (>=2). (PR #80)qsea::getExampleQseaSet() calls in getUMAP() examples with exampleTumourNormal, removing slow synthetic data generation from R CMD check example runs. (PR #77)addNormalisation() examples in \donttest{}: the function requires windows across a range of CpG densities for background estimation, which the pre-filtered example datasets do not provide. (PR #77)plotly PNG device error on headless build servers (PR #75)ragg_png device in PCA vignette chunks to resolve Cairo/X11 dependency issues in CI (PR #75)R CMD check TIMEOUT: skip_long_checks() read options() instead of getOption(), so slow tests never skipped. Also set options(skip_long_checks = TRUE) in tests/testthat.R. (PR #77)qsea::getExampleQseaSet() builds via cachedExampleQset() (helper-fixtures.R) and gated the slowest test_that() blocks behind skip_long_checks(). (PR #77)addHMMcopyCNV(): replaced qsea:::makeGenomeWindows() with a fixed-width GRanges reimplementation, correcting window widths and boundaries. (PR #77)addHyperStableFraction() now uses identical() for the BSgenome check, avoiding an “argument is of length zero” error when the BSgenome parameter is missing (NULL). (PR #77)mixSamples() now reports which sample name(s) are absent from the qseaSet instead of a generic stopifnot() failure, restoring the diagnostics lost when qsea:::checkSamples() was dropped. (PR #77)mixThreeQsetSamples() likewise now names the absent sample(s) rather than failing with a generic stopifnot() message. (PR #77)qsea via @import (R/mesa-package.R), replaced all qsea:::/janitor::: calls with public-API equivalents or inline slot assignments, and declared five data-object names in utils::globalVariables(). (PR #77)LINE_LENGTH notes; where :: cannot be broken across lines, replaced long namespace-qualified names with getExportedValue() (for annotation-package objects in R/genome.R, R/qseaExtra.R) and utils::data() (for package datasets in R/calculateEnrichment.R, R/qseaExtra.R) — both are semantically equivalent to pkg::name but can be formatted across multiple lines (PR #76)\donttest{} across getPCA(), getUMAP(), getDimRed(), plotUMAP(), plotDimRed(), makeQset(), annotateWindows(), getGenomicFeatureDistribution(), plotRegionsHeatmap(), plotGeneHeatmap(), plotGenomicFeatureDistribution(), summariseDMRsByGene(), writeDMRsToExcel(), writeDMRsToBed(), and calculateCGEnrichmentGRanges() — fixes R CMD check TIMEOUT on Bioconductor build machines. (#74)@examples block in plotRegionsHeatmap() that caused identical examples to appear twice in the generated Rd file. (#74)\code{\link[pkg]{function}} syntax — R-devel (4.6) is stricter about package-anchored topic resolution. (#73)hg38UltraStableProbes, plotRegionsHeatmap, renameSamples, and sliceDMRs documentation to stay within 100 characters. (#73)inst/scripts/install_mesa.R — standard BiocManager::install() is sufficient for installation. (#73)devtools::check() and BiocCheck::BiocCheck(). (#73)sliceDMRs to take the ‘top’ DMRs in each contrast, based on a specified ranking column. !24
getMesaGenome(), getMesaTxDb(), and getMesaAnnoDb() functions to complete mesa’s genome management system. Supports hg38, hg19, and mm10 with extensible architecture. !68
plotGenomicFeatureDistribution() now supports multiple genomes via genome, TxDb, and annoDb parameters. Function now works with mesa’s genome system via setMesaGenome() or custom genome builds. No longer limited to hg38. !68
inst/scripts/install_mesa.R: one-shot installer that automatically sets the correct Bioconductor version and validates environment consistency — see README for usage. !72
plotPCA into a submethod for the qsea defined method. !11
plotPCA gains a verbose option to turn off most of the messages produced. !11
plotPCA and plotUMAP now default to filled shapes rather than empty shapes if less than 6 shapes are required. !36
plotPCA and plotUMAP can now specify the shapes used via shapePalette, even if no shape annotation is being given. !36
getSampleTable is now defined for PCA/UMAP objects. !11
plotGeneHeatmap now automatically retries if it fails to connect to biomaRt, and fails with a clear error message if it cannot connect. !44
fdrThres changed to FDRthres in calculateDMRs and subsetWindowsOverBackground. !48
makeQset now checks that the chromosomes provided match with those present in the BSgenome. !32
"PairedAndR1s" coverage method for makeQset will now only process reads that are present in the regions, this should reduce memory requirements and fix issues when _alt chromosomes exist in the bam files. This means the fragment size measurements are now only calculated over the selected regions. !32
plotPCA and plotUMAP no longer take the qseaSet as an input. The PCA/UMAP object has a copy of the sampleTable which may be modified instead. !58
seq_along rather than 1:n throughout. !67
actions/checkout@v2 to v4; added system info step to CI for easier debugging. !71
plotGenomicFeatureDistribution and getGenomicFeatureDistribution internal as they currently only work for hg38. !14
calculateFractionReadsInGRanges internal as it seems to be returning the fraction of windows that overlap not reads. !14
countWindowsAboveCutoff internal as it needs the arguments renaming and better documentation. !14
getAnnotationDataFrame and getAnnotationDataFrameIndividual as they are superseded by getAnnotation and the shift to tidy evaluation via sampleAnnotation in the plotting functions. !14
colnames function definion on a qseaSet, which was not working anyway. !14
dropAvgFragDetails as no longer required. !63
.Rbuildignore to exclude .github, .devcontainer, docs/ and other non-package files from the build — silences related R CMD check notes. !70
installDependencies.R. !72
makeTransposedTable no longer adds chr to the window names even if they already had a chr prefix. !14
... inside plotGeneHeatmap and plotRegionsHeatmap. !14
writeDMRsToBed should now correctly export the files. !14
plotRegionsHeatmap was given more than one region that overlapped one window. !21
addMedipsEnrichmentFactors (thanks @daonslog for reporting). !14
makeQset, renameSamples and renameQsetNames will no longer accept sample names that are not valid column names in R without quotation. !31
fragmentLength when calling makeQset with the CNVmethod = "MeCap" option, and fix an issue with hg19 GRanges. !21
plotPCA now plots a shape column that contains NA values without needing to also specifying NAshape. !36
plotPCA and plotUMAP no longer print a NULLcol or NULLshape column in the legend when using filled shapes. !36
plotPCA and plotUMAP now show the fill colour as opposed to black points in the legend when using filled shapes. !36
fragmentLength when calling makeQset with the CNVmethod = "MeCap" option, and fix an issue with hg19 GRanges. !21
makeQset printed the wrong number of paired reads being filtered out due to having an insert size outside of the selected size range. !32
plotPCA when using ggplot2 4.0.0. !55
plotGenomicFeatureDistribution that occurred with Bioconductor 3.21 when multiple chromosome columns existed after ChIPseeker annotation. !68
plotGeneHeatmap() examples to handle transient Ensembl connection errors during R CMD check. !70
plyranges::mutate() calls throughout the package — plyranges 1.30 no longer re-exports dplyr::mutate(). !72
GRanges-class Rd cross-references in liftOverHg19(), getCGPositions(), and qseaTableToChrGRanges(). !72
plotGeneHeatmap() examples failing during R CMD check due to transient Ensembl connection timeouts. !72
This is the first released version on github, following a lengthy period of internal development. Many things have changed in a major overhaul of the package.
covr coverage.getPCA() and getUMAP() now return an object of class mesaDimRed, which wraps the previous list based output. This object now contains a copy of the sampleTable, which may be edited using mutate and left_join.plotGeneHeatmap.plotPCA() and plotUMAP() no longer require passing the qseaSet, as the sampleTable is stored in the object.setMesaGenome, setMesaTxDb and setMesaAnnoDb to set global defaults for the annotation packages required by annotateWindows. This has the effect that annotateWindows will no longer assume hg38 by default with no arguments.summariseDMRsByGene function now requires annotateWindows to have already been called on the DMRs (previously it called this internally if necessary).poolSamples now returns data frames instead of matrices in the libraries slot.select now works when dropping a column. !6
downSample now works correctly again following changes to how table and enframe interact.calculateDMRs now correctly returns an empty data frame if no DMRs are found.plotPCA now works when colouring by a factor variable.mutate now cannot be used to change the sample_name in the sample table of a qseaSet which breaks the object. renameQsetNames or renameSamples must be used for this.gc_hg38_10kb and map_hg38_10kb (GC and mappability tracks for hg38 at 10kb resolution) for package size reasons.Fixed how the relative enrichment (relH/GoGe) calculation is performed (addMedipsEnrichmentFactors) when using the qsea default method for reads (#1).
Filtering a qseaSet now works correctly when a qseaSet has no cnv data.
Fixed pull to work directly on a qseaSet to return a column of the sampleTable.
Removed mutateQset, filterQset, arrangeQset, sortQset, pullQset, leftJoinQset as these just work on the dplyr verbs directly.
Combined getBetaMeans and getNormalisedReadSum into new function called summariseAcrossWindows. This allows an arbitrary function to be (e.g. mean or sd) to be applied over all the windows in each sample, and returns a data frame with one result per sample.
Added a new function addSummaryAcrossWindows that performs summariseAcrossWindows but returns the qseaSet with the results added to the sampleTable.
Added a function asValidGranges that checks if an object can be coerced to a GRanges object and does so if possible.
Added setMesaGenome function to globally set which genome to be used for plotting functions.
Standardised on using “Windows” instead of “Regions”. For instance, filterRegions is now filterWindows, and plotGRangesHeatmap is now plotRegionsHeatmap. Added a function getWindows to mimic getRegions from qsea.
Complete overhaul of the PCA functionality.
getPCA and plotPCA, and the getPCAwithBatch function has been removed.UMAP functionality added, using the same framework as PCAs, with getUMAP and getPCA. This is still experimental.
Changed pivotDMRsLonger to return columns “group1” and “group2” instead of “sample1” and “sample2”.
In DMR results, moved the betaDelta columns to be after the equivalent adjPval columns instead of all being at the end.
Renamed the contrastsToDo argument of makeDMRs to just contrasts.
mixSamples (formerly mixQsetSamples) no longer sets type and tumour in the sampleTable of the returned qseaSet.
Changes to heatmap plotting functions (plotRegionsHeatmap and plotGeneHeatmap, plotCNVHeatmap):
plotGRangesHeatmap is now renamed as plotRegionsHeatmap
Both support a useGroups argument, to determine whether to average over the “group” column of the sampleTable or not.
Argument signatureGR of plotRegionsHeatmap changed to regionsToOverlap.
Changed from pheatmap package to ComplexHeatmap package for the plotting.
The method of adding sample annotations has been overhauled. This is now specified using sampleAnnotation (instead of annotationCol), and does not support the use of the getAnnotationDataFrame function. These options now directly take the name of the features to be plotted, supporting unquoted tidy evaluation, i.e. all of these work:
sampleAnnotation = group
sampleAnnotation = c(group, type)
sampleAnnotation = c("group","type")
Heatmaps can now have windows annotated with the use of windowAnnotation. This supports unquoted tidy evaluation as well, and can use anything on the qseaSet regions slot or on the regionsToOverlap argument.
The getAnnotationDataFrame and getAnnotationDataFrameIndividual functions have been removed.
The colours for the annotations have been overhauled. These now try to choose appropriate colour scales for continuous data based on whether they are strictly positive or not. For discrete annotations, the colours are set globally for the entire annotation set, to try and prevent the occurrance of different annotations using very similar colours.
getDataTable function can now keep the suffix (e.g. _nrpm or _beta) if required.
removeWindowsOverCutoff and keepWindowsOverCutoff have been replaced by a more general function called subsetWindowsBySignal. This allows for a general function to be specified (for instance mean or max) as well as a threshold, enabling for the filtering of windows based on that function.
Parallelisation of functions is now controlled explicitly by the setMesaParallel function. This must be used to enable multicore evaluation.
When calculating DMRs, by default the qseaSet will now be filtered to only include samples which are present in the contrasts for the calculating of the dispersion estimates in the generalised linear model. This can be controlled by the calcDispersionAll option. The pre-filtering of windows based on expression is unchanged - this only uses samples included in the contrasts.
The difference in mean beta values in the DMR output has been renamed from betaDelta to deltaBeta to reflect the mathematical usage .
Updated documentation in many functions.
Authors updated to include Paddy Harker, Kevin Brennan and Katarzyna Kamieniecka.
Removed exporting of internal functions: dropAvgFragDetails, getBamCoveragePairedAndUnpairedR1, mixThreeQsetSamples, getCGPositions, fitQseaGLM, getDMRsData, subsetWindowsOverBackground.
Renamed many functions throughout the package:
| Previous Function Name | New Function Name |
|---|---|
addQseaNormalisationSteps |
addNormalisation |
annotateData |
annotateWindows |
calculateArrayBetas |
convertToArrayBetaTable |
calculateCpGEnrichment |
calculateCGEnrichment |
calculateCpGEnrichmentGRanges |
calculateCGEnrichmentGRanges |
countWindowsOverCutoff |
countWindowsAboveCutoff |
downsampleQsea |
downSample |
filterRegions |
filterWindows |
liftOverhg19 |
liftOverHg19 |
mixQsetSamples |
mixSamples |
plotDMRUpSet |
plotDMRUpset |
qseaWriteDMRsBeds |
writeDMRsToBed |
qseaWriteDMRsExcel |
writeDMRsToExcel |
relabelQset |
renameSamples |
summariseByGene |
summariseDMRsByGene |
Six functions have been replaced by different functions (detailed above).
| Previous Function | Replacement Function(s) |
|---|---|
|
|
getPCA/plotPCA
|
|
|
summariseAcrossWindows |
|
|
subsetWindowsBySignal |
Renamed data objects:
| Previous data name | New data name |
|---|---|
encodeBlacklist |
ENCODEbadRegions |
examplePairedTumourQset |
exampleTumourNormal |
plotGeneHeatmap now uses bioMaRt to find the gene details, based on the genome or mart supplied.
filterByOverlaps now works when the `qseaSet` regions contains “chr” but the regions to filter by do not or vice versa.
Removed all references to PooledControl sample (previously suggested for normalisation).
Various R CMD check warning issues fixed.!6
filterByOverlaps no longer allows the option to take a list of window ID numbers.
Fixed addMedipsEnrichmentFactors function inside makeQset when using the "qseaPaired" coverageMethod.
Fixed tests for addMedipsEnrichmentFactors.