diff --git a/.Rbuildignore b/.Rbuildignore index 2e84e15..65cc072 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -1,5 +1,4 @@ ^.*\.Rproj$ ^\.Rproj\.user$ - -## Ignore travis config file -^\.travis\.yml$ \ No newline at end of file +^\.travis\.yml$ +^\.github$ diff --git a/.github/.gitignore b/.github/.gitignore new file mode 100644 index 0000000..2d19fc7 --- /dev/null +++ b/.github/.gitignore @@ -0,0 +1 @@ +*.html diff --git a/.github/workflows/check-bioc.yml b/.github/workflows/check-bioc.yml new file mode 100644 index 0000000..eb2c966 --- /dev/null +++ b/.github/workflows/check-bioc.yml @@ -0,0 +1,283 @@ +## Read more about GitHub actions the features of this GitHub Actions workflow +## at https://lcolladotor.github.io/biocthis/articles/biocthis.html#use_bioc_github_action +## +## For more details, check the biocthis developer notes vignette at +## https://lcolladotor.github.io/biocthis/articles/biocthis_dev_notes.html +## +## You can add this workflow to other packages using: +## > biocthis::use_bioc_github_action() +## +## Using GitHub Actions exposes you to many details about how R packages are +## compiled and installed in several operating system.s +### If you need help, please follow the steps listed at +## https://github.com/r-lib/actions#where-to-find-help +## +## If you found an issue specific to biocthis's GHA workflow, please report it +## with the information that will make it easier for others to help you. +## Thank you! + +## Acronyms: +## * GHA: GitHub Action +## * OS: operating system + +on: + push: + pull_request: + +name: R-CMD-check-bioc + +## These environment variables control whether to run GHA code later on that is +## specific to testthat, covr, and pkgdown. +## +## If you need to clear the cache of packages, update the number inside +## cache-version as discussed at https://github.com/r-lib/actions/issues/86. +## Note that you can always run a GHA test without the cache by using the word +## "/nocache" in the commit message. +env: + has_testthat: 'false' + run_covr: 'false' + run_pkgdown: 'true' + has_RUnit: 'true' + cache-version: 'cache-v9' + +jobs: + build-check: + runs-on: ${{ matrix.config.os }} + name: ${{ matrix.config.os }} (R ${{ matrix.config.r }}) (Bioc ${{ matrix.config.bioc }}) + container: ${{ matrix.config.cont }} + ## Environment variables unique to this job. + + strategy: + fail-fast: false + matrix: + config: + ##- { os: ubuntu-latest, r: 'devel', bioc: '3.22', cont: "bioconductor/bioconductor_docker:RELEASE_3_22", rspm: "https://packagemanager.posit.co/cran/__linux__/jammy/latest" } + - { os: ubuntu-latest, r: 'devel', bioc: '3.22'} + - { os: ubuntu-latest, r: '4.5.1', bioc: '3.21', cont: "bioconductor/bioconductor_docker:RELEASE_3_21"} + - { os: macOS-latest, r: '4.5.1', bioc: '3.21'} + - { os: windows-latest, r: '4.5.1', bioc: '3.21'} + + env: + R_REMOTES_NO_ERRORS_FROM_WARNINGS: true + RSPM: ${{ matrix.config.rspm }} + NOT_CRAN: true + TZ: UTC + _R_CHECK_SYSTEM_CLOCK_: FALSE + R_LIBS_USER: tempdir/Library + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + + steps: + + ## Set the R library to the directory matching the + ## R packages cache step further below when running on Docker (Linux). + - name: Set R Library home on Linux + if: runner.os == 'Linux' + uses: r-lib/actions/setup-r@v2 + with: + r-version: ${{ matrix.config.r }} + ## run: | + ## mkdir -p /__w/_temp/Library + ## echo ".libPaths('/__w/_temp/Library')" > ~/.Rprofile + + ## Most of these steps are the same as the ones in + ## https://github.com/r-lib/actions/blob/master/examples/check-standard.yaml + ## If they update their steps, we will also need to update ours. + - name: Checkout Repository + uses: actions/checkout@v4 + + ## R is already included in the Bioconductor docker images + - name: Setup R from r-lib + if: runner.os != 'Linux' + uses: r-lib/actions/setup-r@v2 + with: + r-version: ${{ matrix.config.r }} + + + ## pandoc is already included in the Bioconductor docker images + - name: Setup pandoc from r-lib + if: runner.os != 'Linux' + uses: r-lib/actions/setup-pandoc@v2 + + - name: Query dependencies + run: | + install.packages('remotes') + saveRDS(remotes::dev_package_deps(dependencies = TRUE), ".github/depends.Rds", version = 2) + shell: Rscript {0} + + - name: Cache R packages + if: "!contains(github.event.head_commit.message, '/nocache') && runner.os != 'Linux'" + uses: actions/cache@v4 + with: + path: ${{ env.R_LIBS_USER }} + key: ${{ env.cache-version }}-${{ runner.os }}-biocversion-RELEASE_$${{ matrix.config.bioc }}-$${{ matrix.config.r }}-${{ hashFiles('.github/depends.Rds') }} + restore-keys: ${{ env.cache-version }}-${{ runner.os }}-biocversion-RELEASE_$${{ matrix.config.bioc }}-r-${{ matrix.config.r }}- + + - name: Cache R packages on Linux + if: "!contains(github.event.head_commit.message, '/nocache') && runner.os == 'Linux' " + uses: actions/cache@v4 + with: + path: /home/runner/work/_temp/Library + key: ${{ env.cache-version }}-${{ runner.os }}-biocversion-RELEASE_$${{ matrix.config.bioc }}-r-${{ matrix.config.r }}--${{ hashFiles('.github/depends.Rds') }} + restore-keys: ${{ env.cache-version }}-${{ runner.os }}-biocversion-RELEASE_$${{ matrix.config.bioc }}-r-${{ matrix.config.r }}- + + - name: Install Linux system dependencies + if: runner.os == 'Linux' + run: | + ##sysreqs=$(Rscript -e 'remotes::system_requirements("ubuntu", "20.04")') + ##echo $sysreqs + ##sudo -s eval "$sysreqs" + + ## sysreqs=$(Rscript -e 'cat("apt-get update -y && apt-get install -y", paste(gsub("apt-get install -y ", "", remotes::system_requirements("ubuntu", "20.04")), collapse = " "))') + ## echo $sysreqs + ## sudo -s eval "$sysreqs" + + - name: Install macOS system dependencies + if: matrix.config.os == 'macOS-latest' + run: | + ## Enable installing XML from source if needed + brew install libxml2 + echo "XML_CONFIG=/usr/local/opt/libxml2/bin/xml2-config" >> $GITHUB_ENV + + ## Required to install magick as noted at + ## https://github.com/r-lib/usethis/commit/f1f1e0d10c1ebc75fd4c18fa7e2de4551fd9978f#diff-9bfee71065492f63457918efcd912cf2 + brew install imagemagick@6 + + ## For textshaping, required by ragg, and required by pkgdown + brew install harfbuzz fribidi + + ## For installing usethis's dependency gert + brew install libgit2 + + - name: Install Windows system dependencies + if: runner.os == 'Windows' + run: | + ## Edit below if you have any Windows system dependencies + shell: Rscript {0} + + - name: Install BiocManager + run: | + message(paste('****', Sys.time(), 'installing BiocManager ****')) + remotes::install_cran("BiocManager") + shell: Rscript {0} + + - name: Set BiocVersion + run: | + BiocManager::install(version = "${{ matrix.config.bioc }}", update = FALSE, ask = FALSE) + shell: Rscript {0} + + - name: Install dependencies pass 1 + run: | + ## Try installing the package dependencies in steps. First the local + ## dependencies, then any remaining dependencies to avoid the + ## issues described at + ## https://stat.ethz.ch/pipermail/bioc-devel/2020-April/016675.html + ## https://github.com/r-lib/remotes/issues/296 + ## Ideally, all dependencies should get installed in the first pass. + + ## Pass #1 at installing dependencies + message(paste('****', Sys.time(), 'pass number 1 at installing dependencies: local dependencies ****')) + remotes::install_local(dependencies = TRUE, repos = BiocManager::repositories(), build_vignettes = TRUE, upgrade = TRUE, force = TRUE) + continue-on-error: true + shell: Rscript {0} + + - name: Install dependencies pass 2 + run: | + ## Pass #2 at installing dependencies + message(paste('****', Sys.time(), 'pass number 2 at installing dependencies: any remaining dependencies ****')) + remotes::install_local(dependencies = TRUE, repos = BiocManager::repositories(), build_vignettes = TRUE, upgrade = TRUE, force = TRUE) + + ## For running the checks + message(paste('****', Sys.time(), 'installing rcmdcheck and BiocCheck ****')) + remotes::install_cran("rcmdcheck") + BiocManager::install("BiocCheck") + shell: Rscript {0} + + - name: Install BiocGenerics + if: env.has_RUnit == 'true' + run: | + ## Install BiocGenerics + BiocManager::install("BiocGenerics") + shell: Rscript {0} + + - name: Install covr + if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' && env.run_covr == 'true' && runner.os == 'Linux' + run: | + remotes::install_cran("covr") + shell: Rscript {0} + + - name: Install pkgdown + if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' && env.run_pkgdown == 'true' && runner.os == 'Linux' + run: | + remotes::install_cran("pkgdown") + shell: Rscript {0} + + - name: Session info + run: | + options(width = 100) + pkgs <- installed.packages()[, "Package"] + sessioninfo::session_info(pkgs, include_base = TRUE) + shell: Rscript {0} + + - name: Run CMD check + env: + _R_CHECK_CRAN_INCOMING_: false + run: | + rcmdcheck::rcmdcheck( + args = c("--no-build-vignettes", "--no-manual", "--timings"), + build_args = c("--no-manual", "--no-resave-data"), + error_on = "error", + check_dir = "check" + ) + shell: Rscript {0} + + ## Might need an to add this to the if: && runner.os == 'Linux' + - name: Reveal testthat details + if: env.has_testthat == 'true' + run: find . -name testthat.Rout -exec cat '{}' ';' + + - name: Run RUnit tests + if: env.has_RUnit == 'true' + run: | + BiocGenerics:::testPackage() + shell: Rscript {0} + + - name: Run BiocCheck + run: | + BiocCheck::BiocCheck( + dir('check', 'tar.gz$', full.names = TRUE), + `quit-with-status` = TRUE, + `no-check-R-ver` = TRUE, + `no-check-bioc-help` = TRUE + ) + shell: Rscript {0} + + - name: Test coverage + if: github.ref == 'refs/heads/main' && env.run_covr == 'true' && runner.os == 'Linux' + run: | + covr::codecov() + shell: Rscript {0} + + - name: Install package + if: github.ref == 'refs/heads/main' && env.run_pkgdown == 'true' && runner.os == 'Linux' + run: R CMD INSTALL . + + - name: Deploy package + if: github.ref == 'refs/heads/main' && env.run_pkgdown == 'true' && runner.os == 'Linux' + run: | + git config --global --add safe.directory '*' + git config --local user.name "$GITHUB_ACTOR" + git config --local user.email "$GITHUB_ACTOR@users.noreply.github.com" + Rscript -e "pkgdown::deploy_to_branch(new_process = FALSE)" + shell: bash {0} + ## Note that you need to run pkgdown::deploy_to_branch(new_process = FALSE) + ## at least one locally before this will work. This creates the gh-pages + ## branch (erasing anything you haven't version controlled!) and + ## makes the git history recognizable by pkgdown. + + - name: Upload check results + if: failure() + uses: actions/upload-artifact@master + with: + name: ${{ runner.os }}-biocversion-RELEASE_3_15-r-4.2.2-results + path: check diff --git a/.github/workflows/test-coverage.yml b/.github/workflows/test-coverage.yml new file mode 100644 index 0000000..1b374b2 --- /dev/null +++ b/.github/workflows/test-coverage.yml @@ -0,0 +1,31 @@ +# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples +# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help +on: + push: + pull_request: + +name: test-coverage + +jobs: + test-coverage: + runs-on: ubuntu-latest + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + + steps: + - uses: actions/checkout@v4 + + - uses: r-lib/actions/setup-r@v2 + with: + use-public-rspm: true + + - uses: r-lib/actions/setup-r-dependencies@v2 + with: + extra-packages: any::covr + needs: coverage + + - name: Test coverage + run: covr::codecov(quiet = FALSE) + shell: Rscript {0} + env: + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} diff --git a/.travis.yml b/.travis.yml index 45916a6..e1cb75a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,37 +5,21 @@ sudo: required r: bioc-release # Package caching only makes sense for the release versions. -cache: packages +#cache: packages # Packages from Bioconductor needed -#bioc_packages: -# - BiocParallel -# - GenomicRanges -# - IRanges -# - S4Vectors -# - methods -# - gridExtra -# - BiocStyle -# - BiocGenerics +bioc_required: true # Be strict when checking package warnings_are_errors: true -r_build_args: "--no-manual --no-resave-data --keep-empty-dirs" +r_build_args: "--no-manual --no-resave-data" r_check_args: "--no-build-vignettes --no-manual --timings" -# Package dependencies from CRAN not in DESCRIPTION file -r_binary_packages: - - covr -# - RUnit -# - knitr -# - rmarkdown -# - ggplot2 +# Package dependencies from CRAN +r_packages: + - covr -#r_github_packages: -# - Bioconductor-mirror/rtracklayer@release-3.3 -# - al2na/methylKit - -# To send info to codecov +# When travis end with success, call codecov after_success: - Rscript -e 'library(covr);codecov()' diff --git a/DESCRIPTION b/DESCRIPTION index 2f144f7..a990fbc 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,42 +1,36 @@ Package: methylInheritance -Version: 0.99.1 -Date: 2016-10-25 -Title: Permutation-Based Analysis associating Conserved Differentially - Methylated Elements from One Generation to the Next to a Treatment Effect -Description: Permutation analysis, based on Monte Carlo sampling, for testing - the hypothesis that the number of conserved differentially methylated - elements, between several generations, is associated to an effect - inherited from a treatment and that stochastic effect can be dismissed. -Author: Astrid Deschênes, Pascal Belleau and Arnaud Droit -Author@R: c(person("Astrid", "Deschênes", - email="adeschen@hotmail.com", - role=c("cre","aut")), - person("Pascal", "Belleau", - email="pascal.belleau@crchuq.ulaval.ca", role=c("aut")), - person("Arnaud", "Droit", - email="arnaud.droit@crchuq.ulaval.ca", role=c("aut"))) -Depends: - R (>= 3.3) -Imports: - methylKit, - BiocParallel, - GenomicRanges, - IRanges, - S4Vectors, - methods, - ggplot2, - gridExtra -Suggests: +Version: 1.33.1 +Date: 2021-11-21 +Title: Permutation-Based Analysis associating Conserved Differentially + Methylated Elements Across Multiple Generations to a Treatment Effect +Description: Permutation analysis, based on Monte Carlo sampling, for + testing the hypothesis that the number of conserved + differentially methylated elements, between several + generations, is associated to an effect inherited from a + treatment and that stochastic effect can be dismissed. +Authors@R: c(person("Astrid", "Deschênes", email="adeschen@hotmail.com", + role=c("cre","aut"), comment = c(ORCID = "0000-0001-7846-6749")), + person("Pascal", "Belleau", email="pascal_belleau@hotmail.com", + role=c("aut"), comment = c(ORCID = "0000-0002-0802-1071")), + person("Arnaud", "Droit", + email="arnaud.droit@crchuq.ulaval.ca", role=c("aut"))) +Depends: R (>= 3.5) +Imports: methylKit, BiocParallel, GenomicRanges, IRanges, S4Vectors, + methods, parallel, ggplot2, gridExtra, rebus +Suggests: BiocStyle, BiocGenerics, knitr, rmarkdown, - RUnit + RUnit, + methInheritSim, + testthat (>= 3.0.0) Encoding: UTF-8 License: Artistic-2.0 +URL: https://github.com/adeschen/methylInheritance +BugReports: https://github.com/adeschen/methylInheritance/issues VignetteBuilder: knitr biocViews: BiologicalQuestion, Epigenetics, DNAMethylation, - DifferentialMethylation, MethylSeq, - Software, StatisticalMethod, WholeGenome, Sequencing -Maintainer: Astrid Deschenes -RoxygenNote: 5.0.1 + DifferentialMethylation, MethylSeq, Software, ImmunoOncology, + StatisticalMethod, WholeGenome, Sequencing +RoxygenNote: 7.3.3 diff --git a/NAMESPACE b/NAMESPACE index 9eab9ff..acdab91 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,14 +1,15 @@ # Generated by roxygen2: do not edit by hand S3method(print,methylInheritanceAllResults) +export(calculateSignificantLevel) export(extractInfo) export(loadAllRDSResults) +export(loadConvergenceData) export(mergePermutationAndObservation) +export(plotConvergenceGraph) export(plotGraph) -export(runObservationUsingMethylKitInfo) -export(runObservationUsingRDSFile) -export(runPermutationUsingMethylKitInfo) -export(runPermutationUsingRDSFile) +export(runObservation) +export(runPermutation) importFrom(BiocParallel,MulticoreParam) importFrom(BiocParallel,SnowParam) importFrom(BiocParallel,bplapply) @@ -26,14 +27,19 @@ importFrom(S4Vectors,values) importFrom(ggplot2,aes) importFrom(ggplot2,facet_grid) importFrom(ggplot2,geom_histogram) +importFrom(ggplot2,geom_line) +importFrom(ggplot2,geom_point) importFrom(ggplot2,geom_text) importFrom(ggplot2,geom_vline) importFrom(ggplot2,ggplot) importFrom(ggplot2,labs) importFrom(ggplot2,scale_color_manual) importFrom(ggplot2,theme) +importFrom(ggplot2,xlab) +importFrom(ggplot2,ylab) importFrom(gridExtra,grid.arrange) importFrom(gridExtra,tableGrob) +importFrom(methods,is) importFrom(methods,new) importFrom(methylKit,calculateDiffMeth) importFrom(methylKit,filterByCoverage) @@ -43,3 +49,6 @@ importFrom(methylKit,methRead) importFrom(methylKit,normalizeCoverage) importFrom(methylKit,tileMethylCounts) importFrom(methylKit,unite) +importFrom(parallel,mclapply) +importFrom(parallel,nextRNGSubStream) +importFrom(rebus,number_range) diff --git a/R/methylInheritance.R b/R/methylInheritance.R index 70431e2..7c414cb 100644 --- a/R/methylInheritance.R +++ b/R/methylInheritance.R @@ -8,7 +8,6 @@ #' several generations, is associated to an effect inherited from a treatment #' and that stochastic effect can be dismissed. #' -#' @docType package #' #' @name methylInheritance-package #' @@ -22,33 +21,31 @@ #' Astrid Deschenes #' #' @seealso -#' \itemize{ -#' \item \code{\link{runPermutationUsingRDSFile}} {for running a -#' permutation analysis on the specified multi-generational dataset in -#' RDS format} -#' \item \code{\link{runPermutationUsingMethylKitInfo}} {for running a -#' permutation analysis using a methylKit info object as input} -#' \item \code{\link{runObservationUsingRDSFile}} {for running a -#' observation analysis on the specified multi-generational dataset in -#' RDS format} -#' \item \code{\link{runObservationUsingMethylKitInfo}} {for running a -#' observation analysis using a methylKit info object as input} +#' \describe{ +#' \item{\code{\link{runPermutation}}}{ for running a +#' permutation analysis, and optionally an observation analysis, on a +#' specified multi-generational dataset} +#' \item{\code{\link{runObservation}}}{ for running an +#' observation analysis on a specified multi-generational dataset} #' } #' +#' @return methylInheritance +#' @encoding UTF-8 #' @keywords package -NULL +#' @keywords internal +"_PACKAGE" #' All samples information, formated by \code{methylKit}, in a #' \code{methylRawList} format (for demo purpose). #' -#' The object is a \code{list} with 3 entries. Each entry correspond to the +#' The object is a \code{list} with 3 entries. Each entry corresponds to the #' information for one generation (first entry = first generation, etc..) #' stored in a \code{methylRawList}. -#' There is 12 samples (6 controls and 6 cases) for each generation. Each +#' There are 12 samples (6 controls and 6 cases) for each generation. Each #' sample information is stored in a \code{methylRaw} object. #' #' This dataset can be -#' used to test the \code{runPermutationUsingMethylKitInfo} function. +#' used to test the \code{runPermutation} function. #' #' @name samplesForTransgenerationalAnalysis #' @@ -69,9 +66,10 @@ NULL #' (6 controls and 6 cases) in each generation. #' #' @seealso -#' \itemize{ -#' \item \code{\link{runPermutationUsingMethylKitInfo}} {for running a -#' permutation analysis using methylKit info entry} +#' \describe{ +#' \item{\code{\link{runPermutation}}}{ for running a +#' permutation analysis, and optionally an observation analysis, using +#' multi-generational dataset} #' } #' #' @usage data(samplesForTransgenerationalAnalysis) @@ -84,25 +82,23 @@ NULL #' data(samplesForTransgenerationalAnalysis) #' #' ## Run a permutation analysis -#' \dontrun{runPermutationUsingMethylKitInfo(methylKitInfo = -#' samplesForTransgenerationalAnalysis, type = "sites", nbrPermutations = 3, -#' vSeed = 2001)} +#' runPermutation(methylKitData = samplesForTransgenerationalAnalysis, +#' type = "tiles", nbrPermutations = 2, vSeed = 2332) #' NULL -#' Methylation information from samples over three generations. Information +#' The methylation information from samples over three generations. Information #' for each generation is stored in a #' \code{methylRawList} format (for demo purpose). #' -#' The object is a \code{list} with 3 entries. Each entry correspond to the +#' The object is a \code{list} with 3 entries. Each entry corresponds to the #' information for one generation (first entry = first generation, etc..) -#' stored in a \code{methylRawList} ojbect. -#' There is 12 samples (6 controls and 6 cases) for each generation. Each +#' stored in a \code{methylRawList} object. +#' There are 12 samples (6 controls and 6 cases) for each generation. Each #' sample information is stored in a \code{methylRaw} object. #' -#' This dataset can be -#' used to test \code{runPermutationUsingMethylKitInfo} and -#' {runObservationUsingMethylKitInfo} functions. +#' This dataset can be used to test \code{runPermutation} and +#' \code{runObservation} functions. #' #' @name demoForTransgenerationalAnalysis #' @@ -123,10 +119,11 @@ NULL #' (6 controls and 6 cases) in each generation. #' #' @seealso -#' \itemize{ -#' \item \code{\link{runPermutationUsingMethylKitInfo}} {for running a -#' permutation analysis using methylKit info entry} -#' \item \code{\link{runObservationUsingMethylKitInfo}} {for running a +#' \describe{ +#' \item{\code{\link{runPermutation}}}{ for running a +#' permutation analysis, and optionally an observation analysis, +#' using a multi-generational dataset} +#' \item{\code{\link{runObservation}}}{ for running an #' observation analysis using methylKit info entry} #' } #' @@ -140,22 +137,31 @@ NULL #' data(demoForTransgenerationalAnalysis) #' #' ## Run a permutation analysis -#' \dontrun{(runObservationUsingMethylKitInfo(methylKitInfo = -#' demoForTransgenerationalAnalysis, type = "tiles", nbrPermutations = 3, -#' vSeed = 2001)} +#' runObservation(methylKitData = demoForTransgenerationalAnalysis, +#' outputDir = "test_demo", type = "tiles", vSeed = 2001) +#' +#' ## Get results +#' result <- loadAllRDSResults(analysisResultsDir = "test_demo", +#' permutationResultsDir = NULL, doingSites = FALSE, +#' doingTiles = TRUE) +#' +#' ## Remove result directory +#' if (dir.exists("test_demo")) { +#' unlink("test_demo", recursive = TRUE) +#' } #' NULL #' All observed and permutation results formatted in a -#' \code{methylInheritanceResults} class object (for demo purpose). +#' \code{methylInheritanceResults} class (for demo purpose). #' #' The object is a \code{list} with 2 entries: "OBSERVATION" and #' "PERMUTATION". #' #' This dataset can be -#' used to test the \code{extractInfo} function.The extracted info can be -#' used to calculate the significant level or to create a graph. +#' used to test the \code{extractInfo} function.The extracted information can +#' be used to calculate the significant level or to create a graph. #' #' @name methylInheritanceResults #' @@ -313,9 +319,9 @@ NULL #' generations; the second element, the intersection of the second and third #' generations. #' } -#' \item\code{iAll} a \code{list} containing: +#' \item \code{iAll} a \code{list} containing: #' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer} with 1 entry, +#' \item \code{HYPER} a \code{list} of \code{integer} with 1 entry, #'the number of conserved #' hyper differentially methylated sites between the three consecutive #' generations. @@ -326,7 +332,7 @@ NULL #' } #' \item \code{TILES} a \code{list} containing: #' \itemize{ -#' \item\code{i2} a \code{list} containing: +#' \item \code{i2} a \code{list} containing: #' \itemize{ #' \item \code{HYPER} a \code{list} of \code{integer} with 2 entries, #' the number of conserved @@ -421,8 +427,8 @@ NULL #' } #' #' @seealso -#' \itemize{ -#' \item \code{\link{extractInfo}} {for extracting the +#' \describe{ +#' \item{\code{\link{extractInfo}}}{ for extracting the #' information specific to a subsection of the permutation analysis} #' } #' @@ -439,6 +445,6 @@ NULL #' ## methylated sites (type = sites) between the intersection of 2 #' ## generations (inter = i2): F1 and F2 (position = 1) #' extractInfo(allResults = methylInheritanceResults, -#' type = "sites", inter="i2", 1) +#' type = "sites", inter="i2", 1) #' NULL diff --git a/R/methylInheritanceInternalMethods.R b/R/methylInheritanceInternalMethods.R index c9aaf99..88c6796 100644 --- a/R/methylInheritanceInternalMethods.R +++ b/R/methylInheritanceInternalMethods.R @@ -1,15 +1,17 @@ -#' @title Parameters validation for the -#' \code{\link{runPermutationUsingMethylKitInfo}} function +#' @title Parameters validation for the \code{\link{runPermutation}} function #' #' @description Validation of all parameters needed by the public -#' \code{\link{runPermutationUsingMethylKitInfo}} function. -#' -#' @param methylKitInfo a \code{list} of \code{methylRawList} entries. Each -#' \code{methylRawList} contains all the \code{methylRaw} entries related to -#' one generation. The number of generations must correspond to the number -#' of entries in the \code{methylKitInfo}.At least 2 generations +#' \code{\link{runPermutation}} function. +#' +#' @param methylKitData a \code{list} of \code{methylRawList} entries or the +#' name of the RDS file containing the \code{list}. Each +#' \code{methylRawList} entry must contain all the \code{methylRaw} entries +#' related to one generation (first entry = first generation, second +#' entry = second generation, etc..). The number of generations must +#' correspond to the number +#' of entries in the \code{methylKitData}. At least 2 generations #' must be present to do a permutation analysis. More information can be found -#' in the Bioconductor methylKit package. +#' in the methylKit package. #' #' @param type One of the "sites","tiles" or "both" strings. Specifies the type #' of differentially methylated elements should be returned. For @@ -80,6 +82,16 @@ #' needed. When a value inferior or equal to zero is given, a random integer #' is used. #' +#' @param restartCalculation a \code{logical}, when \code{TRUE}, only +#' permutations that don't have an associated RDS result file are run. Useful +#' to restart a permutation analysis that has been interrupted. +#' +#' @param saveInfoByGeneration a \code{logical}, when \code{TRUE}, the +#' information about differentially methylated sites and tiles for each +#' generation is saved in a RDS file. The information is saved in a different +#' file for each permutation. The files are only saved when the +#' \code{outputDir} is not \code{NULL}. +#' #' @return \code{0} indicating that all parameters validations have been #' successful. #' @@ -89,41 +101,49 @@ #' data(samplesForTransgenerationalAnalysis) #' #' ## The function returns 0 when all paramaters are valid -#' methylInheritance:::validateRunPermutationUsingMethylKitInfo( -#' methylKitInfo = samplesForTransgenerationalAnalysis, type = "sites", -#' outputDir = NULL, runObservedAnalysis = TRUE, -#' nbrPermutations = 10000, nbrCores = 1, -#' nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 25, qvalue = 0.01, -#' maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, -#' tileSize = 1000, stepSize = 500, vSeed = 12) +#' methylInheritance:::validateRunPermutation( +#' methylKitData = samplesForTransgenerationalAnalysis, type = "sites", +#' outputDir = "test", runObservedAnalysis = TRUE, +#' nbrPermutations = 10000, nbrCores = 1, +#' nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 25, qvalue = 0.01, +#' maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, +#' tileSize = 1000, stepSize = 500, vSeed = 12, restartCalculation = FALSE, +#' saveInfoByGeneration = FALSE) #' #' ## The function raises an error when at least one paramater is not valid -#' \dontrun{methylInheritance:::validateRunPermutationUsingMethylKitInfo( -#' methylKitInfo = "HI",type = "tiles", outputDir = NULL, -#' runObservedAnalysis = FALSE, nbrPermutations = 10000, nbrCores = 1, -#' nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 25, qvalue = 0.01, -#' maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, -#' tileSize = 1000, stepSize = 500, vSeed = 12)} +#' \dontrun{methylInheritance:::validateRunPermutation( +#' methylKitData = "HI", type = "tiles", outputDir = "test", +#' runObservedAnalysis = FALSE, nbrPermutations = 10000, nbrCores = 1, +#' nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 25, qvalue = 0.01, +#' maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, +#' tileSize = 1000, stepSize = 500, vSeed = 12, restartCalculation = FALSE, +#' saveInfoByGeneration = FALSE)} #' #' @author Astrid Deschenes #' @importFrom S4Vectors isSingleInteger isSingleNumber #' @keywords internal -validateRunPermutationUsingMethylKitInfo <- function(methylKitInfo, - type, outputDir, runObservedAnalysis, - nbrPermutations, nbrCores, - nbrCoresDiffMeth, - minReads, minMethDiff, qvalue, - maxPercReads, destrand, - minCovBasesForTiles, tileSize, - stepSize, vSeed) { - - ## Validate that methylKitInfo is a list of methylRawList - if (class(methylKitInfo) != "list" || - !all(sapply(methylKitInfo, class) == "methylRawList")) { - stop(paste0("methylKitInfo must be a list containing ", - "\"methylRawList\" entries; each entry must contain ", - "all \"methylRaw\" objects related to one generation")) - } +validateRunPermutation <- function(methylKitData, + type, outputDir, runObservedAnalysis, + nbrPermutations, nbrCores, nbrCoresDiffMeth, + minReads, minMethDiff, qvalue, maxPercReads, + destrand, minCovBasesForTiles, tileSize, + stepSize, vSeed, restartCalculation, + saveInfoByGeneration) { + + ## Validate methylKitData, outputDir, nbrCoresDiffMeth + ## minReads, minMethDiff, qvalue, maxPercReads, destrand, + ## minCovBasesForTiles, tileSize, stepSize, vSeed + validateRunObservation(methylKitData = methylKitData, + type = type, outputDir = outputDir, + nbrCoresDiffMeth = nbrCoresDiffMeth, + minReads = minReads, minMethDiff = minMethDiff, + qvalue = qvalue, + maxPercReads = maxPercReads, destrand = destrand, + minCovBasesForTiles = minCovBasesForTiles, + tileSize = tileSize, + stepSize = stepSize, vSeed = vSeed, + restartCalculation = restartCalculation, + saveInfoByGeneration = saveInfoByGeneration) ## Validate that the runObservedAnalysis is a logical if (!is.logical(runObservedAnalysis)) { @@ -148,32 +168,24 @@ validateRunPermutationUsingMethylKitInfo <- function(methylKitInfo, stop("nbrPermutations must be a positive integer or numeric") } - ## Validate all the other parameters - validateRunObservationUsingMethylKitInfo(methylKitInfo = methylKitInfo, - type = type, outputDir = outputDir, - nbrCores = nbrCores, - nbrCoresDiffMeth = nbrCoresDiffMeth, - minReads = minReads, minMethDiff = minMethDiff, - qvalue = qvalue, - maxPercReads = maxPercReads, destrand = destrand, - minCovBasesForTiles = minCovBasesForTiles, - tileSize = tileSize, - stepSize = stepSize, vSeed = vSeed) + return(0) } #' @title Validation of some parameters of the -#' \code{\link{runObservationUsingMethylKitInfo}} function +#' \code{\link{runObservation}} function #' #' @description Validation of some parameters needed by the public -#' \code{\link{runObservationUsingMethylKitInfo}} function. +#' \code{\link{runObservation}} function. #' -#' @param methylKitInfo a \code{list} of \code{methylRawList} entries. Each +#' @param methylKitData a \code{list} of \code{methylRawList} entries or the +#' name of the RDS file containing the list. Each #' \code{methylRawList} contains all the \code{methylRaw} entries related to -#' one generation. The number of generations must correspond to the number -#' of entries in the \code{methylKitInfo}. At least 2 generations -#' must be present to do a permutation analysis. More information can be found -#' in the Bioconductor methylKit package. +#' one generation (first entry = first generation, second entry = second +#' generation, etc..). The number of generations must correspond to the number +#' of entries in the \code{methylKitData}. At least 2 generations +#' must be present to calculate the conserved elements. More information can +#' be found in the methylKit package. #' #' @param type One of the "sites","tiles" or "both" strings. Specifies the type #' of differentially methylated elements should be returned. For @@ -184,9 +196,6 @@ validateRunPermutationUsingMethylKitInfo <- function(methylKitInfo, #' the results of the permutation. If the directory does not exist, it will #' be created. #' -#' @param nbrCores a positive \code{integer}, the number of cores to use when -#' processing the analysis. -#' #' @param nbrCoresDiffMeth a positive \code{integer}, the number of cores #' to use for parallel differential methylation calculations.Parameter #' used for both sites and tiles analysis. The parameter @@ -238,6 +247,16 @@ validateRunPermutationUsingMethylKitInfo <- function(methylKitInfo, #' needed. When a value inferior or equal to zero is given, a random integer #' is used. #' +#' @param restartCalculation a \code{logical}, when \code{TRUE}, only +#' permutations that don't have an associated RDS result file are run. Useful +#' to restart a permutation analysis that has been interrupted. +#' +#' @param saveInfoByGeneration a \code{logical}, when \code{TRUE}, the +#' information about differentially methylated sites and tiles for each +#' generation is saved in a RDS file. The information is saved in a different +#' file for each permutation. The files are only saved when the +#' \code{outputDir} is not \code{NULL}. +#' #' @return \code{0} indicating that all parameters validations have been #' successful. #' @@ -247,54 +266,56 @@ validateRunPermutationUsingMethylKitInfo <- function(methylKitInfo, #' data(samplesForTransgenerationalAnalysis) #' #' ## The function returns 0 when all paramaters are valid -#' methylInheritance:::validateRunObservationUsingMethylKitInfo( -#' methylKitInfo = samplesForTransgenerationalAnalysis, type = "sites", -#' outputDir = NULL, nbrCores = 1, -#' nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 25, qvalue = 0.01, -#' maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, -#' tileSize = 1000, stepSize = 500, vSeed = 12) +#' methylInheritance:::validateRunObservation( +#' methylKitData = samplesForTransgenerationalAnalysis, type = "sites", +#' outputDir = "test", nbrCoresDiffMeth = 1, minReads = 10, +#' minMethDiff = 25, qvalue = 0.01, +#' maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, +#' tileSize = 1000, stepSize = 500, vSeed = 12, restartCalculation = TRUE, +#' saveInfoByGeneration = FALSE) #' #' ## The function raises an error when at least one paramater is not valid -#' \dontrun{methylInheritance:::validateRunObservationUsingMethylKitInfo( -#' methylKitInfo = samplesForTransgenerationalAnalysis, -#' type = "tiles", outputDir = NULL, nbrCores = 1, -#' nbrCoresDiffMeth = 1, minReads = "HI", minMethDiff = 25, qvalue = 0.01, -#' maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, -#' tileSize = 1000, stepSize = 500, vSeed = 12)} +#' \dontrun{methylInheritance:::validateRunObservation( +#' methylKitData = samplesForTransgenerationalAnalysis, +#' type = "tiles", outputDir = "test_02", nbrCoresDiffMeth = 1, +#' minReads = "HI", minMethDiff = 25, qvalue = 0.01, +#' maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, +#' tileSize = 1000, stepSize = 500, vSeed = 12, restartCalculation = FALSE, +#' saveInfoByGeneration = FALSE)} #' #' @author Astrid Deschenes #' @importFrom S4Vectors isSingleInteger isSingleNumber +#' @importFrom methods is #' @keywords internal -validateRunObservationUsingMethylKitInfo <- function(methylKitInfo, - type, outputDir, nbrCores, +validateRunObservation <- function(methylKitData, + type, outputDir, nbrCoresDiffMeth, minReads, minMethDiff, qvalue, maxPercReads, destrand, minCovBasesForTiles, tileSize, - stepSize, vSeed) { + stepSize, vSeed, restartCalculation, + saveInfoByGeneration) { + + ## Validate that methylKitData is a valid RDS file when string is passed + if (is.character(methylKitData)) { + if (!file.exists(methylKitData)) { + stop(paste0("The file \"", methylKitData, "\" does not exist.")) + } else { + methylKitData <- readRDS(methylKitData) + } + } - ## Validate that methylKitInfo is a list of methylRawList - if (class(methylKitInfo) != "list" || - !all(sapply(methylKitInfo, class) == "methylRawList")) { - stop(paste0("methylKitInfo must be a list containing ", + ## Validate that methylKitData is a list of methylRawList + if (!is(methylKitData, "list") || + !all(sapply(methylKitData, class) == "methylRawList")) { + stop(paste0("methylKitData must be a list containing ", "\"methylRawList\" entries; each entry must contain ", "all \"methylRaw\" objects related to one generation")) } ## Validate that the output_dir is an not empty string - if (!is.null(outputDir) && !is.character(outputDir)) { - stop("output_dir must be a character string or NULL") - } - - ## Validate that nbrCores is an positive integer - if (!(isSingleInteger(nbrCores) || isSingleNumber(nbrCores)) || - as.integer(nbrCores) < 1) { - stop("nbrCores must be a positive integer or numeric") - } - - ## Validate that nbrCores is set to 1 on Windows system - if (Sys.info()["sysname"] == "Windows" && as.integer(nbrCores) != 1) { - stop("nbrCores must be 1 on a Windows system.") + if (!is.character(outputDir)) { + stop("output_dir must be a character string") } ## Validate that nbrCoresDiffMeth is an positive integer @@ -358,12 +379,21 @@ validateRunObservationUsingMethylKitInfo <- function(methylKitInfo, as.integer(stepSize) < 1) { stop("stepSize must be a positive integer or numeric") } - } + ## Validate that vSeed is an integer if (!(isSingleInteger(vSeed) || isSingleNumber(vSeed))) { stop("vSeed must be an integer or numeric") } + ## Validate that restartCalculation is a logical + if (!is.logical(restartCalculation)) { + stop("restartCalculation must be a logical") + } + + ## Validate that saveInfoByGeneration is a logical + if (!is.logical(saveInfoByGeneration)) { + stop("saveInfoByGeneration must be a logical") + } return(0) } @@ -376,8 +406,7 @@ validateRunObservationUsingMethylKitInfo <- function(methylKitInfo, #' \code{\link{extractInfo}} function. #' #' @param allResults a \code{list} as created by the -#' \code{runPermutationUsingMethylKitInfo}, the -#' \code{runPermutationUsingRDSFile} or the \code{loadAllRDSResults} functions. +#' \code{runPermutation} or the \code{loadAllRDSResults} functions. #' #' @param type One of the \code{"sites"} or \code{"tiles"} strings. #' Specifies the type @@ -405,24 +434,25 @@ validateRunObservationUsingMethylKitInfo <- function(methylKitInfo, #' #' ## The function returns 0 when all paramaters are valid #' methylInheritance:::validateExtractInfo( -#' allResults = methylInheritanceResults, type = "sites", -#' inter = "i2", 2) +#' allResults = methylInheritanceResults, type = "sites", +#' inter = "i2", 2) #' #' ## The function raises an error when at least one paramater is not valid #' \dontrun{methylInheritance:::validateExtractInfo( -#' allResults = methylInheritanceResults, type = "sites", -#' inter = "i2", 12)} +#' allResults = methylInheritanceResults, type = "sites", +#' inter = "i2", 12)} #' #' @author Astrid Deschenes #' @importFrom S4Vectors isSingleInteger isSingleNumber +#' @importFrom methods is #' @keywords internal validateExtractInfo <- function(allResults, type, inter, position) { - if (position < 1) { + if (!is.numeric(position) || floor(position) != position || position < 1) { stop("position must be a positive integer") } - if (!"methylInheritanceAllResults" %in% class(allResults)) { + if (!is(allResults, "methylInheritanceAllResults")) { stop("allResults must be of class \"methylInheritanceAllResults\"") } @@ -447,7 +477,7 @@ validateExtractInfo <- function(allResults, type, inter, position) { if (position > length(allResults$OBSERVATION[[toupper(type)]][[inter]])) { stop(paste0("position must correspond to a valid entry in the \"", - "allResults$OBSERVATION[[", toupper(type), "]][[", inter, "]]")) + "allResults$OBSERVATION[[", toupper(type), "]][[", inter, "]]\"")) } if (is.null(allResults$PERMUTATION)) { @@ -484,7 +514,7 @@ validateExtractInfo <- function(allResults, type, inter, position) { #' @description Validation of some parameters needed by the public #' \code{\link{mergePermutationAndObservation}} function. #' -#' @param @param permutationResults a \code{list} with 1 entry called +#' @param permutationResults a \code{list} with 1 entry called #' \code{PERMUTATION}. The \code{PERMUTATION} entry is a \code{list} with #' a number of entries corresponding #' to the number of permutations that have been processed. Each entry contains @@ -493,7 +523,7 @@ validateExtractInfo <- function(allResults, type, inter, position) { #' @param observationResults a \code{list} with 1 entry called #' \code{OBSERVATION}. The \code{OBSERVATION} entry is a \code{list} containing #' the result obtained -#' with the observed dataset (not permutated). +#' with the observed dataset (not shuffled). #' #' @return \code{0} indicating that all parameters validations have been #' successful. @@ -505,9 +535,9 @@ validateExtractInfo <- function(allResults, type, inter, position) { #' observed[["OBSERVATION"]] <- list() #' observed[["OBSERVATION"]][["SITES"]] <- list() #' observed[["OBSERVATION"]][["SITES"]][["i2"]] <- list(HYPER = list(11, 10), -#' HYPO = list(13, 12)) +#' HYPO = list(13, 12)) #' observed[["OBSERVATION"]][["SITES"]][["iAll"]] <- list(HYPER = list(1), -#' HYPO = list(3)) +#' HYPO = list(3)) #' #' ## Create a permutation result containing only 1 permutation result #' ## Real perumtations results would have more entries @@ -516,17 +546,17 @@ validateExtractInfo <- function(allResults, type, inter, position) { #' permutated[["PERMUTATION"]][[1]] <- list() #' permutated[["PERMUTATION"]][[1]][["SITES"]] <- list() #' permutated[["PERMUTATION"]][[1]][["SITES"]][["i2"]] <- list(HYPER = -#' list(11, 12), HYPO = list(8, 11)) +#' list(11, 12), HYPO = list(8, 11)) #' permutated[["PERMUTATION"]][[1]][["SITES"]][["iAll"]] <- list(HYPER = -#' list(0), HYPO = list(1)) +#' list(0), HYPO = list(1)) #' #' ## Merge permutation and observation results #' methylInheritance:::validateMergePermutationAndObservation( -#' permutationResults = permutated, observationResults = observed) +#' permutationResults = permutated, observationResults = observed) #' #' ## The function raises an error when at least one paramater is not valid #' \dontrun{methylInheritance:::validateMergePermutationAndObservation( -#' permutationResults = permutated, observationResults = NULL)} +#' permutationResults = permutated, observationResults = NULL)} #' #' @author Astrid Deschenes #' @keywords internal @@ -552,6 +582,76 @@ validateMergePermutationAndObservation <- function(permutationResults, return(0) } +#' @title Validation of some parameters of the +#' \code{\link{loadConvergenceData}} function +#' +#' @description Validation of some parameters needed by the public +#' \code{\link{loadConvergenceData}} function. +#' +#' @param analysisResultsDir a \code{character} string, the path to the +#' directory that contains the analysis results. The path can be the same as +#' for the \code{permutatioNResultsDir} parameter. +#' +#' @param permutationResultsDir a \code{character} string, the path to the +#' directory that contains the permutation results. The path can be the same +#' as for the \code{analysisResultsDir} parameter. +#' +#' @param position a positive \code{integer}, the position in the \code{list} +#' where the information will be extracted. +#' +#' @param by a \code{integer}, the increment of the number of permutations +#' where the significant level is tested. Default: 100. +#' +#' @return \code{0} indicating that all parameters validations have been +#' successful. +#' +#' @examples +#' +#' ## Get the name of the directory where files are stored +#' filesDir <- system.file("extdata", "TEST", package="methylInheritance") +#' +#' ## Merge permutation and observation results +#' methylInheritance:::validateLoadConvergenceData(analysisResultsDir = +#' filesDir, permutationResults = filesDir, position = 1, by = 1) +#' +#' ## The function raises an error when at least one paramater is not valid +#' \dontrun{methylInheritance:::validateLoadConvergenceData( +#' analysisResultsDir = filesDir, permutationResults = filesDir, +#' position = "hello", by = 1))} +#' +#' @author Astrid Deschenes, Pascal Belleau +#' @keywords internal +validateLoadConvergenceData <- function(analysisResultsDir, + permutationResultsDir, position, by) { + + ## Validate that the analysisResultsDir is an not empty string + if (!is.null(analysisResultsDir) && !is.character(analysisResultsDir)) { + stop("analysisResultsDir must be a character string") + if (!dir.exists(analysisResultsDir)) { + stop("analysisResultsDir must be an existing directory") + } + } + + ## Validate that the permutationResultsDir is an not empty string + if (!is.null(permutationResultsDir) && + !is.character(permutationResultsDir)) { + stop("permutationResultsDir must be a character string") + if (!dir.exists(permutationResultsDir)) { + stop("permutationResultsDir must be an existing directory") + } + } + + if (!is.numeric(position) || floor(position) != position || position < 1) { + stop("position must be a positive integer") + } + + if (!is.numeric(by) || floor(by) != by || by < 1) { + stop("by must be a positive integer") + } + + return(0) +} + #' @title Transform results from a CpG site or region analysis done on mutliple #' generations into a \code{list} of \code{GRanges} objects @@ -589,14 +689,13 @@ validateMergePermutationAndObservation <- function(permutationResults, #' @examples #' #' ## Load permutation results on sites -#' permutationResultsFile <- dir(system.file("extdata", -#' package = "methylInheritance"), pattern = "permutationResultsForSites.RDS", -#' full.names = TRUE) +#' permutationResultsFile <- system.file("extdata", +#' "permutationResultsForSites.RDS", package="methylInheritance") #' permutationResults <- readRDS(permutationResultsFile) #' #' ## Transform result to GRanges #' resultsGR <- methylInheritance:::getGRangesFromMethylDiff(methDiff = -#' permutationResults, pDiff = 10, qvalue = 0.01, type = "hyper") +#' permutationResults, pDiff = 10, qvalue = 0.01, type = "hyper") #' #' @author Pascal Belleau #' @importFrom methylKit getMethylDiff @@ -605,10 +704,12 @@ validateMergePermutationAndObservation <- function(permutationResults, #' @keywords internal getGRangesFromMethylDiff <- function(methDiff, pDiff, qvalue, type = c("all", "hyper", "hypo")) { + # Validate type value + type <- match.arg(type) ## Transform each methylDiff object present in the list to a ## GRanges object - methDiffK <- lapply(1:length(methDiff), FUN = function(i, methDiff, + methDiffK <- lapply(seq_len(length(methDiff)), FUN = function(i, methDiff, pDiff, qCut, typeD) { methK <- getMethylDiff(methDiff[[i]], difference = pDiff, qvalue = qCut, type = typeD) @@ -659,14 +760,13 @@ getGRangesFromMethylDiff <- function(methDiff, pDiff, qvalue, #' @examples #' #' ## Load permutation results on sites -#' permutationResultsFile <- dir(system.file("extdata", -#' package = "methylInheritance"), pattern = "permutationResultsForSites.RDS", -#' full.names = TRUE) +#' permutationResultsFile <- system.file("extdata", +#' "permutationResultsForSites.RDS", package="methylInheritance") #' permutationResults <- readRDS(permutationResultsFile) #' #' ## Transform result to GRanges #' resultsGR <- methylInheritance:::getGRangesFromMethylDiff(methDiff = -#' permutationResults, pDiff = 10, qvalue = 0.01, type = "hyper") +#' permutationResults, pDiff = 10, qvalue = 0.01, type = "hyper") #' #' ## Extract inter generational conserved sites #' conservedSitesGR <- methylInheritance:::interGeneration(resultsGR) @@ -675,7 +775,7 @@ getGRangesFromMethylDiff <- function(methDiff, pDiff, qvalue, #' @importFrom GenomicRanges intersect GRanges #' @importFrom S4Vectors DataFrame values<- values #' @keywords internal -interGeneration <- function(resultAllGenGR){ +interGeneration <- function(resultAllGenGR) { lInter <- list("i2" = list(), "iAll" = list()) @@ -730,18 +830,24 @@ interGeneration <- function(resultAllGenGR){ #' results of the permutation analysis for tiles is created when #' \code{doingTiles} = \code{TRUE}. Default: \code{FALSE}. #' +#' @param saveInfoByGeneration a \code{logical}, when \code{TRUE}, the +#' information about differentially methylated sites and tiles for each +#' generation is saved in a RDS file. The information is saved in a different +#' file for each permutation. +#' #' @return \code{0} when all directories are created without problem. #' #' @examples #' #' ## Create an output directory for SITES only -#' \dontrun{createOutputDir(outputDir = "testSites", doingSites = TRUE, -#' doingTiles = FALSE)} +#' methylInheritance:::createOutputDir(outputDir = "testSites", +#' doingSites = TRUE, doingTiles = FALSE, saveInfoByGeneration = TRUE) #' #' @author Astrid Deschenes #' @keywords internal createOutputDir <- function(outputDir, doingSites = TRUE, - doingTiles = FALSE) { + doingTiles = FALSE, + saveInfoByGeneration) { # Create directories for output files if (!dir.exists(outputDir)) { @@ -764,6 +870,13 @@ createOutputDir <- function(outputDir, doingSites = TRUE, } } + # Create directory for the information for each generation + if (saveInfoByGeneration) { + dirName <- paste0(outputDir, "InfoByGeneration") + if (!dir.exists(dirName)) { + dir.create(dirName, showWarnings = TRUE) + } + } return(0) } @@ -778,22 +891,28 @@ createOutputDir <- function(outputDir, doingSites = TRUE, #' analysis is saved in a RDS file when an directory is #' specified. #' -#' @param methylInfoForAllGenerations a \code{list} containing the -#' following elements: -#' \itemize{ -#' \item \code{sample} a \code{list} of \code{methylRawList} entries, each -#' \code{methylRawList} contains all the \code{methylRaw} entries related to -#' one generation. The number of generations must correspond to the number -#' of entries in the \code{methylKitInfo}. At least 2 generations -#' must be present to do a permutation analysis. -#' \item \code{id} an integer, the permutation id. -#' } +#' @param id an \code{integer}, the unique identification of the permutation. +#' When \code{id} is \code{0}, the analysis is done on the real dataset. +#' +#' @param methylInfoForAllGenerations a \code{list} of \code{methylRawList} +#' entries. Each +#' \code{methylRawList} entry must contain all the \code{methylRaw} entries +#' related to one generation (first entry = first generation, second +#' entry = second generation, etc..). The number of generations must +#' correspond to the number +#' of entries in the \code{methylKitData}. At least 2 generations +#' must be present to make a permutation analysis. More information can be +#' found in the methylKit package. #' #' @param type One of the "sites","tiles" or "both" strings. Specifies the type #' of differentially methylated elements should be returned. For #' retrieving differentially methylated bases type="sites"; for #' differentially methylated regions type="tiles". Default: "both". #' +#' @param outputDir a string, the name of the directory that will contain +#' the results of the permutation. If the directory does not +#' exist, it will be created. +#' #' @param nbrCoresDiffMeth a positive integer, the number of cores to use for #' parallel differential methylation calculations.Parameter used for both #' sites and tiles analysis. The parameter @@ -805,6 +924,11 @@ createOutputDir <- function(outputDir, doingSites = TRUE, #' coverage than this count are discarded. The parameter #' correspond to the \code{lo.count} parameter in the \code{methylKit} package. #' +#' @param minMethDiff a positive integer betwwen [0,100], the absolute value +#' of methylation percentage change between cases and controls. The parameter +#' correspond to the \code{difference} parameter in the +#' package \code{methylKit}. Default: \code{10}. +#' #' @param qvalue a positive \code{double} inferior to \code{1}, the cutoff #' for qvalue of differential methylation statistic. Default: \code{0.01}. #' @@ -816,25 +940,16 @@ createOutputDir <- function(outputDir, doingSites = TRUE, #' correspond to the \code{hi.perc} parameter in the \code{methylKit} package. #' Default: \code{99.9}. #' -#' @param minMethDiff a positive integer betwwen [0,100], the absolute value -#' of methylation -#' percentage change between cases and controls. The parameter -#' correspond to the \code{difference} parameter in the -#' package \code{methylKit}. -#' Default: \code{10}. -#' #' @param destrand a logical, when \code{TRUE} will merge reads on both #' strands of a CpG dinucleotide to provide better coverage. Only advised #' when looking at CpG methylation. Parameter used for both -#' sites and tiles analysis. -#' Default: \code{FALSE}. +#' sites and tiles analysis. Default: \code{FALSE}. #' #' @param minCovBasesForTiles a non-negative integer, the minimum number of #' bases to be covered in a given tiling window. The parameter #' corresponds to the \code{cov.bases} parameter in the #' package \code{methylKit}. -#' Only used when \code{doingTiles} = -#' \code{TRUE}. Default: \code{0}. +#' Only used when \code{doingTiles} = \code{TRUE}. Default: \code{0}. #' #' @param tileSize a positive integer, the size of the tiling window. The #' parameter corresponds to the \code{win.size} parameter in @@ -846,11 +961,14 @@ createOutputDir <- function(outputDir, doingSites = TRUE, #' the \code{methylKit} package. Only #' used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}. #' -#' @param doingSites a logical, when \code{TRUE} will do the analysis on the -#' CpG dinucleotide sites. Default: \code{TRUE}. +#' @param restartCalculation a \code{logical}, when \code{TRUE}, only +#' permutations that don't have a RDS result final are run. #' -#' @param doingTiles a logical, when \code{TRUE} will do the analysis on the -#' tiles. Default: \code{FALSE}. +#' @param saveInfoByGeneration a \code{logical}, when \code{TRUE}, the +#' information about differentially methylated sites and tiles for each +#' generation is saved in a RDS file. The information is saved in a different +#' file for each permutation. The files are = saved in the +#' \code{outputDir}. #' #' @return a \code{list} containing the following elements: #' \itemize{ @@ -888,7 +1006,7 @@ createOutputDir <- function(outputDir, doingSites = TRUE, #' } #' \item \code{TILES} Only present when \code{type} = \code{"tiles"} or #' \code{"both"}, a \code{list} containing: -#' itemize{ +#' \itemize{ #' \item\code{i2} a \code{list} containing: #' \itemize{ #' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved @@ -924,36 +1042,46 @@ createOutputDir <- function(outputDir, doingSites = TRUE, #' #' ## Load methyl information #' data(samplesForTransgenerationalAnalysis) -#' info <- list(sample = samplesForTransgenerationalAnalysis, id = 100) #' #' ## Run a permutation analysis -#' \dontrun{methylInheritance:::runOnePermutationOnAllGenerations( -#' methylInfoForAllGenerations = info, type = "sites", outputDir = NULL, -#' nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.01, -#' maxPercReads = 99.9, destrand = FALSE, minCovBasesForTiles = 0, -#' tileSize = 1000, stepSize = 1000)} +#' methylInheritance:::runOnePermutationOnAllGenerations(id = 2, +#' methylInfoForAllGenerations = samplesForTransgenerationalAnalysis, +#' type = "tiles", outputDir = NULL, +#' nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.01, +#' maxPercReads = 99.9, destrand = FALSE, minCovBasesForTiles = 0, +#' tileSize = 1000, stepSize = 1000, restartCalculation = FALSE) #' #' @author Astrid Deschenes, Pascal Belleau #' @importFrom methylKit filterByCoverage normalizeCoverage unite #' calculateDiffMeth getMethylDiff getData tileMethylCounts methRead #' @importFrom GenomicRanges width #' @keywords internal -runOnePermutationOnAllGenerations <- function(methylInfoForAllGenerations, +runOnePermutationOnAllGenerations <- function(id, + methylInfoForAllGenerations, type = c("both", "sites", "tiles"), outputDir = NULL, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.01, maxPercReads = 99.9, destrand = FALSE, minCovBasesForTiles = 0, - tileSize = 1000, stepSize = 1000) { + tileSize = 1000, stepSize = 1000, + restartCalculation, saveInfoByGeneration) { + + # Validate type value + type <- match.arg(type) doTiles <- any(type %in% c("tiles", "both")) doSites <- any(type %in% c("sites", "both")) ## Extract info from input list - methylRawForAllGenerations <- methylInfoForAllGenerations$sample - id <- methylInfoForAllGenerations$id - + if (id > 0) { + ## Use permuted dataset, permutation needed + methylRawForAllGenerations <- formatInputMethylData(methylKitData = + methylInfoForAllGenerations) + } else { + ## Use real dataset, no permutation needed + methylRawForAllGenerations <- methylInfoForAllGenerations + } nbrGenerations <- length(methylRawForAllGenerations) ## Preparing list that will receive final results @@ -965,12 +1093,22 @@ runOnePermutationOnAllGenerations <- function(methylInfoForAllGenerations, permutationList[["SITES"]] <- list() } - for (i in 1:nbrGenerations) { + readyTiles <- FALSE + if (doTiles && restartCalculation) { + readyTiles <- isInterGenerationResults(outputDir, id, "tiles") + } + + readySites <- FALSE + if (doSites && restartCalculation) { + readySites <- isInterGenerationResults(outputDir, id, "sites") + } + + for (i in seq_len(nbrGenerations)) { allSamplesForOneGeneration <- methylRawForAllGenerations[[i]] ## SITES - if (doSites) { + if (doSites && !readySites) { ## Filter sites by coverage filtered.sites <- filterByCoverage(allSamplesForOneGeneration, @@ -990,12 +1128,16 @@ runOnePermutationOnAllGenerations <- function(methylInfoForAllGenerations, } ## Get differentially methylated sites - permutationList[["SITES"]][[i]] <- calculateDiffMeth(meth.sites, - num.cores = nbrCoresDiffMeth) + allSites <- suppressMessages(suppressWarnings( + calculateDiffMeth(meth.sites, mc.cores = nbrCoresDiffMeth))) + + permutationList[["SITES"]][[i]] <- suppressWarnings( + getMethylDiff(allSites, difference = minMethDiff, + qvalue = qvalue)) } ## TILES - if (doTiles) { + if (doTiles && !readyTiles) { ## Summarize methylated base counts over tilling windows tiles <- tileMethylCounts(allSamplesForOneGeneration, @@ -1017,97 +1159,124 @@ runOnePermutationOnAllGenerations <- function(methylInfoForAllGenerations, meth.tiles <- unite(filtered.tiles, destrand = destrand) ## Get diff methylated tiles - permutationList[["TILES"]][[i]] <- calculateDiffMeth(meth.tiles, - num.cores = nbrCoresDiffMeth) + allTiles <- suppressMessages(suppressWarnings( + calculateDiffMeth(meth.tiles, mc.cores = nbrCoresDiffMeth))) + + permutationList[["TILES"]][[i]] <- suppressWarnings( + getMethylDiff(allTiles, difference = minMethDiff, + qvalue = qvalue)) } } + ## Save all sites results per generation in RDS file when specified + if (!is.null(outputDir) && saveInfoByGeneration && doSites && !readySites) { + saveRDS(object = permutationList[["SITES"]], file = paste0(outputDir, + "InfoByGeneration/DMEByGeneration_sites_", id, ".RDS")) + } + + ## Save all tiles results per generation in RDS file when specified + if (!is.null(outputDir) && saveInfoByGeneration && doTiles && !readyTiles) { + saveRDS(object = permutationList[["TILES"]], file = paste0(outputDir, + "InfoByGeneration/DMEByGeneration_tiles_", id, ".RDS")) + } + permutationFinal <- list() ## Calculate the number of SITES in the intersection if (doSites) { - - ## Transform initial results to GRanges - resultGR <- getGRangesFromMethylDiff(permutationList[["SITES"]], + if (!readySites) { + ## Transform initial results to GRanges + resultGR <- getGRangesFromMethylDiff(permutationList[["SITES"]], minMethDiff, qvalue, type = "all") - ## Extract inter generational conserved sites - result <- interGeneration(resultGR) + ## Extract inter generational conserved sites + result <- interGeneration(resultGR) - ## Save results in RDS file when specified - if (!is.null(outputDir)) { - saveInterGenerationResults(outputDir, id, type = "sites", result) + ## Save results in RDS file when specified + if (!is.null(outputDir)) { + saveInterGenerationResults(outputDir, id, type = "sites", + result) + } + } else { + result<- readInterGenerationResults(outputDir, id, type = "sites") } ## Create list that will contain final results - permutationFinal[["SITES"]] <- list() - permutationFinal[["SITES"]][["i2"]] <- list() - permutationFinal[["SITES"]][["i2"]][["HYPER"]] <- list() - permutationFinal[["SITES"]][["i2"]][["HYPO"]] <- list() - permutationFinal[["SITES"]][["iAll"]][["HYPER"]] <- list() - permutationFinal[["SITES"]][["iAll"]][["HYPO"]] <- list() - - permutationFinal[["SITES"]][["i2"]][["HYPER"]] <- lapply(result$i2, - FUN = function(x) {sum(width(x[x$typeDiff > 0]))}) - - permutationFinal[["SITES"]][["i2"]][["HYPO"]] <- lapply(result$i2, - FUN = function(x) {sum(width(x[x$typeDiff < 0]))}) - - - permutationFinal[["SITES"]][["iAll"]][["HYPER"]] <- lapply(result$iAll, - FUN = function(x) {sum(width(x[x$typeDiff > 0]))}) - - permutationFinal[["SITES"]][["iAll"]][["HYPO"]] <- lapply(result$iAll, - FUN = function(x) {sum(width(x[x$typeDiff < 0]))}) + # permutationFinal[["SITES"]] <- list() + # permutationFinal[["SITES"]][["i2"]] <- list() + # permutationFinal[["SITES"]][["i2"]][["HYPER"]] <- list() + # permutationFinal[["SITES"]][["i2"]][["HYPO"]] <- list() + # permutationFinal[["SITES"]][["iAll"]][["HYPER"]] <- list() + # permutationFinal[["SITES"]][["iAll"]][["HYPO"]] <- list() + # + # permutationFinal[["SITES"]][["i2"]][["HYPER"]] <- lapply(result$i2, + # FUN = function(x) {sum(width(x[x$typeDiff > 0]))}) + # + # permutationFinal[["SITES"]][["i2"]][["HYPO"]] <- lapply(result$i2, + # FUN = function(x) {sum(width(x[x$typeDiff < 0]))}) + # + # permutationFinal[["SITES"]][["iAll"]][["HYPER"]] <- lapply( + # result$iAll, + # FUN = function(x) {sum(width(x[x$typeDiff > 0]))}) + # + # permutationFinal[["SITES"]][["iAll"]][["HYPO"]] <- lapply( + # result$iAll, + # FUN = function(x) {sum(width(x[x$typeDiff < 0]))}) } ## Calculate the number of TILES in the intersection if (doTiles) { - - ## Transform initial results to GRanges - resultGR <- getGRangesFromMethylDiff(permutationList[["TILES"]], + if (!readyTiles) { + ## Transform initial results to GRanges + resultGR <- getGRangesFromMethylDiff(permutationList[["TILES"]], minMethDiff, qvalue, type = "all") - ## Extract inter generational conserved tiles - result <- interGeneration(resultGR) + ## Extract inter generational conserved tiles + result <- interGeneration(resultGR) - ## Save results in RDS file when specified - if (!is.null(outputDir)) { - saveInterGenerationResults(outputDir, id, type = "tiles", result) + ## Save results in RDS file when specified + if (!is.null(outputDir)) { + saveInterGenerationResults(outputDir, id, type = "tiles", + result) + } + } else { + result <- readInterGenerationResults(outputDir, id, type = "tiles") } ## Create list that will contain final results - permutationFinal[["TILES"]] <- list() - permutationFinal[["TILES"]][["i2"]] <- list() - permutationFinal[["TILES"]][["i2"]][["HYPER"]] <- list() - permutationFinal[["TILES"]][["i2"]][["HYPO"]] <- list() - permutationFinal[["TILES"]][["iAll"]][["HYPER"]] <- list() - permutationFinal[["TILES"]][["iAll"]][["HYPO"]] <- list() - - permutationFinal[["TILES"]][["i2"]][["HYPER"]] <- lapply(result$i2, - FUN = function(x) {sum(width(x[x$typeDiff > 0]))}) - - permutationFinal[["TILES"]][["i2"]][["HYPO"]] <- lapply(result$i2, - FUN = function(x) {sum(width(x[x$typeDiff < 0]))}) - - permutationFinal[["TILES"]][["iAll"]][["HYPER"]] <- lapply(result$iAll, - FUN = function(x) {sum(width(x[x$typeDiff > 0]))}) - - permutationFinal[["TILES"]][["iAll"]][["HYPO"]] <- lapply(result$iAll, - FUN = function(x) {sum(width(x[x$typeDiff < 0]))}) + # permutationFinal[["TILES"]] <- list() + # permutationFinal[["TILES"]][["i2"]] <- list() + # permutationFinal[["TILES"]][["i2"]][["HYPER"]] <- list() + # permutationFinal[["TILES"]][["i2"]][["HYPO"]] <- list() + # permutationFinal[["TILES"]][["iAll"]][["HYPER"]] <- list() + # permutationFinal[["TILES"]][["iAll"]][["HYPO"]] <- list() + # + # permutationFinal[["TILES"]][["i2"]][["HYPER"]] <- lapply(result$i2, + # FUN = function(x) {sum(width(x[x$typeDiff > 0]))}) + # + # permutationFinal[["TILES"]][["i2"]][["HYPO"]] <- lapply(result$i2, + # FUN = function(x) {sum(width(x[x$typeDiff < 0]))}) + # + # permutationFinal[["TILES"]][["iAll"]][["HYPER"]] <- lapply( + # result$iAll, + # FUN = function(x) {sum(width(x[x$typeDiff > 0]))}) + # + # permutationFinal[["TILES"]][["iAll"]][["HYPO"]] <- lapply( + # result$iAll, + # FUN = function(x) {sum(width(x[x$typeDiff < 0]))}) } - return(permutationFinal) + return(0) } #' @title Save the result of on CpG site or tile analysis on all generations. -#' The anaysis can come from observed or permutated dataset. Each case is +#' The anaysis can come from observed or shuffled dataset. Each case is #' saved with a different extension. #' #' @description Save the result of on CpG site or tile analysis on all #' generations. The results are saved in a RDS file. The anaysis can have been -#' done on the observed or permutated dataset. +#' done on the observed or shuffled dataset. #' Each permutation is saved using its identifiant in the file name. #' #' @param outputDir a string of \code{character}, the name of the directory @@ -1115,19 +1284,13 @@ runOnePermutationOnAllGenerations <- function(methylInfoForAllGenerations, #' the results of the permutation. The name should end with a slash. The #' directory should already exists. #' -#' @param type One of the \code{"sites"} or \code{"tiles"} strings. Specifies -#' the type -#' of differentially methylated elements should be returned. For -#' retrieving differentially methylated bases \code{type} =\code{"sites"}; for -#' differentially methylated regions \code{type} = \code{"tiles"}. Default: -#' \code{"both"}. -#' -#' @param permutationID an \code{integer}, the identifiant of the permutation. +#' @param permutationID an \code{integer}, the identifier of the permutation. #' When the \code{permutationID} = \code{0}, the results are considered as the #' observed results and are saved in a file with the "_observed_results.RDS" #' extension. When the \code{permutationID} != \code{0}, the results are #' considered as permutation results and are saved in a file with the -#' "_permutation_{permutationID}.RDS" extension. +#' "_permutation_permutationID.RDS" extension. Where permutationID is the +#' identifier of the permutation. #' #' @param type One of the \code{"sites"} or \code{"tiles"} strings. Specifies #' the type of differentially methylated elements should be saved. @@ -1143,22 +1306,26 @@ runOnePermutationOnAllGenerations <- function(methylInfoForAllGenerations, #' @examples #' #' ## Load permutation results on sites -#' permutationResultsFile <- dir(system.file("extdata", -#' package = "methylInheritance"), pattern = "permutationResultsForSites.RDS", -#' full.names = TRUE) +#' +#' permutationResultsFile <- system.file("extdata", +#' "permutationResultsForSites.RDS", package="methylInheritance") #' permutationResults <- readRDS(permutationResultsFile) #' #' ## Transform result to GRanges #' resultsGR <- methylInheritance:::getGRangesFromMethylDiff(methDiff = -#' permutationResults, pDiff = 10, qvalue = 0.01, type = "hyper") +#' permutationResults, pDiff = 10, qvalue = 0.01, type = "hyper") #' #' ## Extract inter-generationally conserved sites #' interGenerationResult <- methylInheritance:::interGeneration(resultsGR) #' +#' ## Create directories +#' dir.create("TEST", showWarnings = TRUE) +#' dir.create("TEST/SITES", showWarnings = TRUE) +#' #' ## Save results -#' \dontrun{methylInheritance:::saveInterGenerationResults( -#' outputDir = "TEST", permutationID=100, type = "sites", -#' interGenerationResult = interGenerationResult)} +#' methylInheritance:::saveInterGenerationResults( +#' outputDir = "TEST/", permutationID=100, type = "sites", +#' interGenerationResult = interGenerationResult) #' #' @author Astrid Deschenes, Pascal Belleau #' @keywords internal @@ -1182,6 +1349,108 @@ saveInterGenerationResults <- function(outputDir, permutationID, } +#' @title Verify if a specific file containing intergenerational results +#' exists or not. +#' +#' @description Verify if a specific file containing intergenerational results +#' exists or not. +#' +#' @param outputDir a string of \code{character}, the name of the directory +#' that will contain +#' the results of the permutation. The name should end with a slash. The +#' directory should already exists. +#' +#' @param permutationID an \code{integer}, the identifier of the permutation. +#' When the \code{permutationID} = \code{0}, the results are considered as the +#' observed results and are saved in a file with the "_observed_results.RDS" +#' extension. When the \code{permutationID} != \code{0}, the results are +#' considered as permutation results and are saved in a file with the +#' "_permutation_permutationID.RDS" extension where permutationID is the +#' identifier of the permutation. +#' +#' @param type One of the \code{"sites"} or \code{"tiles"} strings. Specifies +#' the type of differentially methylated elements should be saved. +#' Default: \code{"sites"}. +#' +#' @return \code{TRUE} when file present; otherwise \code{FALSE}. +#' +#' @examples +#' +#' ## Get the name of the directory where the file is stored +#' filesDir <- system.file("extdata", "TEST", package="methylInheritance") +#' +#' ## Verify that DMS intergenerational results for the observed data exists +#' methylInheritance:::isInterGenerationResults(outputDir = +#' paste0(filesDir, "/"), 0, "sites") +#' +#' @author Astrid Deschenes, Pascal Belleau +#' @keywords internal +isInterGenerationResults <- function(outputDir, permutationID, + type = c("sites", "tiles")) { + + if (permutationID != 0) { + result <- file.exists(paste0(outputDir, toupper(type), "/", + toupper(type), "_permutation_", permutationID, ".RDS")) + } else { + result <- file.exists(paste0(outputDir, toupper(type), "/", + toupper(type), "_observed_results.RDS")) + } + + return(result) +} + +#' @title Read and return intergenerational results contained in a +#' RDS file +#' +#' @description Read and return intergenerational results contained in a +#' RDS file +#' +#' @param outputDir a string of \code{character}, the name of the directory +#' that will contain +#' the results of the permutation. The name should end with a slash. The +#' directory should already exists. +#' +#' @param permutationID an \code{integer}, the identifier of the permutation. +#' When the \code{permutationID} = \code{0}, the results are considered as the +#' observed results and are saved in a file with the "_observed_results.RDS" +#' extension. When the \code{permutationID} != \code{0}, the results are +#' considered as permutation results and are saved in a file with the +#' "_permutation_permutationID.RDS" extension. Where permutationID is the +#' identifier of the permutation. +#' +#' @param type One of the \code{"sites"} or \code{"tiles"} strings. Specifies +#' the type of differentially methylated elements should be saved. +#' Default: \code{"sites"}. +#' +#' @return a \code{list} containing the intergenerational results for the +#' specified permutation. +#' +#' @examples +#' +#' ## Get the name of the directory where the file is stored +#' filesDir <- system.file("extdata", "TEST", package="methylInheritance") +#' +#' ## Read DMS intergenerational results for the observed data +#' methylInheritance:::readInterGenerationResults(outputDir = +#' paste0(filesDir, "/"), 0, "sites") +#' +#' @author Astrid Deschenes, Pascal Belleau +#' @keywords internal +readInterGenerationResults <- function(outputDir, permutationID, + type = c("sites", "tiles")) { + + if (permutationID != 0) { + result <- readRDS(file = paste0(outputDir, toupper(type), "/", + toupper(type), "_permutation_", permutationID, ".RDS")) + } else { + result <- readRDS(file = paste0(outputDir, toupper(type), "/", + toupper(type), "_observed_results.RDS")) + } + + return(result) +} + + #' @title Extract the number of conserved differentially methylated #' elements in \code{GRanges}. #' @@ -1247,12 +1516,11 @@ saveInterGenerationResults <- function(outputDir, permutationID, #' @examples #' #' ## Get the name of the directory where the file is stored -#' filesDir <- dir(system.file("extdata", package = "methylInheritance"), -#' pattern = "TEST", full.names = TRUE) +#' filesDir <- system.file("extdata", "TEST", package="methylInheritance") #' #' ## Load file containing results from a observation analysis #' obsResults <- readRDS(file = paste0(filesDir, -#' "/SITES/SITES_observed_results.RDS")) +#' "/SITES/SITES_observed_results.RDS")) #' #' ## Create data structure using information form the observation analysis #' formatedResults <- methylInheritance:::createDataStructure(obsResults) @@ -1280,4 +1548,139 @@ createDataStructure <- function(interGenerationGR) { return(result) } +#' @title Permute dataset +#' +#' @description Permute dataset and format it to be ready for an analysis +#' +#' @param methylKitData a \code{list} of \code{methylRawList} entries. Each +#' \code{methylRawList} entry must contain all the \code{methylRaw} entries +#' related to one generation (first entry = first generation, second +#' entry = second generation, etc..). The number of generations must +#' correspond to the number +#' of entries in the \code{methylKitData}. At least 2 generations +#' must be present to make a permutation analysis. More information can be +#' found in the methylKit package. +#' +#' @return a \code{list} of \code{methylRawList} entries. +#' +#' @examples +#' +#' ## Load dataset +#' data("samplesForTransgenerationalAnalysis") +#' +#' methylInheritance:::formatInputMethylData(samplesForTransgenerationalAnalysis) +#' +#' @author Astrid Deschenes, Pascal Belleau +#' @importFrom methods new +#' @keywords internal +formatInputMethylData <- function(methylKitData) { + + ## Extract information + nbGenerations <- length(methylKitData) + nbSamplesByGeneration <- sapply(methylKitData, length) + nbSamples <- sum(nbSamplesByGeneration) + allSamples <- unlist(methylKitData, recursive = FALSE) + + ## Random sample + permutationSample <- sample(seq_len(nbSamples)) + + ## Create list that will contain information for all generations + ## related to the same permutation analysis + permutationList <- list() + start <- 1 + for (j in seq_len(nbGenerations)) { + end <- start + nbSamplesByGeneration[j] - 1 + samplePos <- permutationSample[start:end] + treatment <- methylKitData[[j]]@treatment + newSampleList <- new("methylRawList", allSamples[samplePos], + treatment = treatment) + permutationList[[j]] <- newSampleList + start <- end + 1 + } + + return(permutationList) +} + +#' @title Calculate significant level for hypo and hyper conserved elements +#' +#' @description Calculate significant level for hypo and hyper conserved +#' elements using permutation results as well as observed results +#' +#' @param formatForGraphDataFrame a \code{data.frame} containing the +#' observation results (using real +#' data) and the permutation results (using shuffled data). Both hyper and +#' hypo differentially conserved methylation results must be present. The +#' \code{data.frame} must have 3 columns : "TYPE", "RESULT" and "SOURCE". +#' The "TYPE" can be either "HYPER" or "HYPO". The "RESULT" is the number +#' of conserved differentially elements. The "SOURCE" can be either +#' "OBSERVATION" or "PERMUTATION". +#' +#' @return a list containing two elements: +#' \itemize{ +#' \item \code{HYPER} a \code{double}, the significant level for the +#' hyper differentially methylated conserved elements +#' \item \code{HYPO} a \code{double}, the significant level for the +#' hypo differentially methylated conserved elements +#' } +#' +#' @examples +#' +#' ## Loading dataset containing all results +#' data(methylInheritanceResults) +#' +#' ## Extract information for the intersection between conserved differentially +#' ## methylated sites (type = sites) between the intersection of 2 +#' ## generations (inter = i2): F2 and F3 (position = 2) +#' info <- extractInfo(allResults = methylInheritanceResults, +#' type = "sites", inter="i2", 2) +#' +#' ## Create graph +#' methylInheritance:::calculateSignificantLevel(info) +#' +#' @author Astrid Deschenes, Pascal Belleau +#' @export +calculateSignificantLevel <- function(formatForGraphDataFrame) { + + ## Observed results + observedData <- subset(formatForGraphDataFrame, + formatForGraphDataFrame$SOURCE == "OBSERVATION") + + ## HYPO results + hypoDataSet <- subset(formatForGraphDataFrame, + formatForGraphDataFrame$TYPE == "HYPO") + hypoTotal <- as.double(nrow(hypoDataSet)) + hypoNumber <- observedData[observedData$TYPE == "HYPO",]$RESULT + signifLevelHypo <- nrow(subset(hypoDataSet, + hypoDataSet$RESULT >= hypoNumber))/hypoTotal + + ## HYPER results + hyperDataSet <- subset(formatForGraphDataFrame, + formatForGraphDataFrame$TYPE == "HYPER") + hyperTotal <- as.double(nrow(hyperDataSet)) + hyperNumber <- observedData[observedData$TYPE == "HYPER",]$RESULT + signifLevelHyper <- nrow(subset(hyperDataSet, + hyperDataSet$RESULT >= hyperNumber))/hyperTotal + + return(list(HYPER=signifLevelHyper, HYPO=signifLevelHypo)) +} + +createDataFrameFromOneResult <- function(oneResult, type=c("sites", "tiles", + source=c("OBSERVATION", "PERMUTATION"))) { + if (type == "sites") { + tt <- unlist(oneResult$SITES) + } else { + tt <- unlist(oneResult$TILES) + } + + tt.names <- sapply(names(tt), function(x) {strsplit(x, "[.]")}) + tt.analysis <- sapply(tt.names, function(x) {return(x[[1]])}) + tt.types <- sapply(tt.names, function(x) {return(x[[2]])}) + + result <- data.frame(SOURCE=rep(source, length(tt)), + ELEMENT = rep(toupper(type), length(tt)), + ANALYSIS = tt.analysis, TYPE = tt.types, + RESULT=tt, stringsAsFactors = FALSE, row.names = NULL) + + return(result) +} diff --git a/R/methylInheritanceMethods.R b/R/methylInheritanceMethods.R index ad21f19..1971e01 100644 --- a/R/methylInheritanceMethods.R +++ b/R/methylInheritanceMethods.R @@ -1,5 +1,4 @@ -#' @title Run all permutations on the specified multi-generational dataset in -#' RDS format +#' @title Run all permutations on the specified multi-generational dataset #' #' @description Run a permutation analysis, based on Monte Carlo sampling, #' for testing the hypothesis that the number of conserved differentially @@ -7,303 +6,21 @@ #' several generations, is associated to an effect inherited from a treatment #' and that stochastic effect can be dismissed. #' -#' The observation analysis can also be run (optional). All permutation -#' results can also be saved in RDS files (optional). -#' -#' @param methylKitRDSFile a string, the name of the RDS file containing the -#' methylKit objet used for the permutation analysis. The RDS file must -#' hold a \code{list} of \code{methylRawList} entries, each -#' \code{methylRawList} contains all the \code{methylRaw} entries related to -#' one generation (first entry = first generation, second entry = second -#' generation, etc..). The number of generations must correspond to the number -#' of entries in the \code{methylKitInfo}.At least 2 generations -#' must be present to do a permutation analysis. More information can be found -#' in the methylKit package -#' -#' @param type One of the "sites","tiles" or "both" strings. Specifies the type -#' of differentially methylated elements should be returned. For -#' retrieving differentially methylated bases \code{type} = \code{"sites"}; -#' for differentially methylated regions type="tiles". Default: "both". -#' -#' @param outputDir a string, the name of the directory that will contain -#' the results of the permutation or \code{NULL}. If the directory does not -#' exist, it will be created. When \code{NULL}, the results of the permutation -#' are not saved. Default: \code{NULL}. -#' -#' @param runObservationAnalysis a \code{logical}, when -#' \code{runObservationAnalysis} -#' = \code{TRUE}, a CpG analysis on the observed dataset is done. Default: -#' \code{TRUE}. -#' -#' @param nbrPermutations, a positive \code{integer}, the total number of -#' permutations that is going to be done. Default: \code{1000}. -#' -#' @param nbrCores a positive \code{integer}, the number of cores to use when -#' processing the analysis. Default: \code{1} and always \code{1} for Windows. -#' -#' @param nbrCoresDiffMeth a positive \code{integer}, the number of cores -#' to use for parallel differential methylation calculations.Parameter -#' used for both sites and tiles analysis. The parameter -#' corresponds to the \code{num.cores} parameter in the package -#' \code{methylKit}. -#' Default: \code{1} and always \code{1} for Windows. -#' -#' @param minReads a positive \code{integer} Bases and regions having lower -#' coverage than this count are discarded. The parameter -#' correspond to the \code{lo.count} parameter in the package \code{methylKit}. -#' -#' @param minMethDiff a positive \code{double} betwwen [0,100], the absolute -#' value of methylation percentage change between cases and controls. The -#' parameter correspond to the \code{difference} parameter in -#' the package \code{methylKit}. Default: \code{10}. -#' -#' @param qvalue a positive \code{double} betwwen [0,1], the cutoff -#' for qvalue of differential methylation statistic. Default: \code{0.01}. -#' -#' @param maxPercReads a \code{double} between [0,100], the percentile of read -#' counts that is going to be used as upper cutoff. Bases ore regions -#' having higher -#' coverage than this percentile are discarded. Parameter used for both CpG -#' sites and tiles analysis. The parameter -#' correspond to the \code{hi.perc} parameter in the package \code{methylKit}. -#' Default: \code{99.9}. -#' -#' @param destrand a \code{logical}, when \code{TRUE} will merge reads on both -#' strands of a CpG dinucleotide to provide better coverage. Only advised -#' when looking at CpG methylation. Parameter used for both CpG -#' sites and tiles analysis. -#' Default: \code{FALSE}. -#' -#' @param minCovBasesForTiles a non-negative \code{integer}, the minimum -#' number of bases to be covered in a given tiling window. The parameter -#' corresponds to the \code{cov.bases} parameter in the package -#' \code{methylKit}. -#' Only used when \code{doingTiles} = -#' \code{TRUE}. Default: \code{0}. -#' -#' @param tileSize a positive \code{integer}, the size of the tiling window. -#' The parameter corresponds to the \code{win.size} parameter in -#' the package \code{methylKit}. Only -#' used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}. -#' -#' @param stepSize a positive \code{integer}, the step size of tiling windows. -#' The parameter corresponds to the \code{stepSize} parameter in -#' the package \code{methylKit}. Only -#' used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}. -#' -#' @param vSeed a \code{integer}, a seed used when reproducible results are -#' needed. When a value inferior or equal to zero is given, a random integer -#' is used. Default: \code{-1}. -#' -#' @return a \code{list} of class \code{} when a \code{runObservationAnalysis} -#' = \code{TRUE}; otherwise a \code{list}. The returned \code{list} -#' containing the following elements: -#' \itemize{ -#' \item \code{OBSERVATION} Only present when \code{runObservationAnalysis} = -#' \code{TRUE}, a \code{list} containing: -#' \itemize{ -#' \item \code{SITES} Only present when \code{type} = \code{"sites"} or -#' \code{"both"}, a \code{list} containing: -#' \itemize{ -#' \item\code{i2} a \code{list} containing: -#' \itemize{ -#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated sites between two consecutive generations. -#' The first element represents the intersection of the first and second -#' generations; the second element, the intersection of the second and third -#' generations; etc.. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated sites between two consecutive generations.The -#' first element represents the intersection of the first and second -#' generations; the second element, the intersection of the second and third -#' generations; etc.. -#' } -#' \item\code{iAll} a \code{list} containing: -#' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated sites between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number -#' of generations. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated sites between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of -#' generations. -#' } -#' } -#' \item \code{TILES} Only present when \code{type} = \code{"tiles"} or -#' \code{"both"}, a \code{list} containing: -#' \itemize{ -#' \item\code{i2} a \code{list} containing: -#' \itemize{ -#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated positions between two consecutive -#' generations. The first element represents the intersection of the -#' first and second generations; the second element, the intersection of -#' the second and third generations; etc.. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated positions between two consecutive -#' generations.The first element represents the intersection of the first and -#' second generations; the second element, the intersection of the second -#' and third generations; etc.. -#' } -#' \item\code{iAll} a \code{list} containing: -#' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated positions between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number -#' of generations. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated positions between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of -#' generations. -#' } -#' } -#' } -#' \item \code{PERMUTATION} a \code{list} -#' containing \code{nbrPermutations} entries. Each entry is -#' a \code{list} containing: -#' \itemize{ -#' \item \code{SITES} Only present when \code{type} = \code{"sites"} or -#' \code{"both"}, a \code{list} containing: -#' \itemize{ -#' \item\code{i2} a \code{list} containing: -#' \itemize{ -#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated sites between two consecutive generations. -#' The first element represents the intersection of the first and second -#' generations; the second element, the intersection of the second and third -#' generations; etc.. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated sites between two consecutive generations.The -#' first element represents the intersection of the first and second -#' generations; the second element, the intersection of the second and third -#' generations; etc.. -#' } -#' \item\code{iAll} a \code{list} containing: -#' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated sites between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number -#' of generations. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated sites between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of -#' generations. -#' } -#' } -#' \item \code{TILES} Only present when \code{type} = \code{"tiles"} or -#' \code{"both"}, a \code{list} containing: -#' \itemize{ -#' \item\code{i2} a \code{list} containing: -#' \itemize{ -#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated positions between two consecutive -#' generations. The first element represents the intersection of the -#' first and second generations; the second element, the intersection of -#' the second and third generations; etc.. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated positions between two consecutive -#' generations.The first element represents the intersection of the first and -#' second generations; the second element, the intersection of the second -#' and third generations; etc.. -#' } -#' \item\code{iAll} a \code{list} containing: -#' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated positions between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number -#' of generations. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated positions between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of -#' generations. -#' } -#' } -#' } -#' } -#' -#' @examples -#' -#' ## Path to a methylKit RDS file -#' methylFile <- dir(system.file("extdata", package = "methylInheritance"), -#' pattern = "methylObj_001.RDS", full.names = TRUE) -#' -#' ## Run a permutation analysis -#' \dontrun{runPermutationUsingRDSFile(methylKitRDSFile = methylFile, -#' type = "sites", nbrPermutations = 10, vSeed = 2001)} -#' -#' @author Astrid Deschenes, Pascal Belleau -#' @export -runPermutationUsingRDSFile <- function(methylKitRDSFile, - type=c("both", "sites", "tiles"), - outputDir=NULL, - runObservationAnalysis=TRUE, - nbrPermutations=1000, - nbrCores=1, - nbrCoresDiffMeth=1, - minReads=10, - minMethDiff=10, - qvalue=0.01, - maxPercReads=99.9, - destrand=FALSE, - minCovBasesForTiles=0, - tileSize=1000, - stepSize=1000, - vSeed=-1) { - - ## Validate that methylKitRDSFile is an existing file - if (!file.exists(methylKitRDSFile)) { - stop(paste0("The file \"", methylKitRDSFile, "\" does not exist.")) - } - - ## Extract information from RDS file - methylInfo <- readRDS(methylKitRDSFile) - - ## Call permutation analysis with the methylInfo object as an parameter - runPermutationUsingMethylKitInfo(methylInfo, type, outputDir, - runObservationAnalysis, - nbrPermutations, nbrCores, nbrCoresDiffMeth, - minReads, minMethDiff, qvalue, maxPercReads, - destrand, minCovBasesForTiles, tileSize, stepSize, - vSeed) -} - - -#' @title Run all permutations on the specified multi-generational dataset in -#' RDS format -#' -#' @description Run a permutation analysis, based on Monte Carlo sampling, -#' for testing the hypothesis that the number of conserved differentially -#' methylated elements (sites, tiles or both), between -#' several generations, is associated to an effect inherited from a treatment -#' and that stochastic effect can be dismissed. +#' The multi-generational dataset or the name of the RDS file that contains the +#' dataset can be used as input. #' #' The observation analysis can also be run (optional). All permutation -#' results can also be saved in RDS files (optional). -#' -#' @param methylKitInfo a \code{list} of \code{methylRawList} entries, each -#' \code{methylRawList} contains all the \code{methylRaw} entries related to -#' one generation (first entry = first generation, second entry = second -#' generation, etc..). The number of generations must correspond to the number -#' of entries in the \code{methylKitInfo}.At least 2 generations -#' must be present to do a permutation analysis. More information can be found -#' in the methylKit package. +#' results are saved in RDS files. +#' +#' @param methylKitData a \code{list} of \code{methylRawList} entries or the +#' name of the RDS file containing the \code{list}. Each +#' \code{methylRawList} entry must contain all the \code{methylRaw} entries +#' related to one generation (first entry = first generation, second +#' entry = second generation, etc..). The number of generations must +#' correspond to the number +#' of entries in the \code{methylKitData}. At least 2 generations +#' must be present to make a permutation analysis. More information can be +#' found in the methylKit package. #' #' @param type One of the "sites","tiles" or "both" strings. Specifies the type #' of differentially methylated elements should be returned. For @@ -311,9 +28,8 @@ runPermutationUsingRDSFile <- function(methylKitRDSFile, #' differentially methylated regions type="tiles". Default: "both". #' #' @param outputDir a string, the name of the directory that will contain -#' the results of the permutation or \code{NULL}. If the directory does not -#' exist, it will be created. When \code{NULL}, the results of the permutation -#' are not saved. Default: \code{NULL}. +#' the results of the permutation. If the directory does not +#' exist, it will be created. Default: \code{"output"}. #' #' @param runObservationAnalysis a \code{logical}, when #' \code{runObservationAnalysis} = \code{TRUE}, a CpG analysis on the @@ -326,7 +42,7 @@ runPermutationUsingRDSFile <- function(methylKitRDSFile, #' processing the analysis. Default: \code{1} and always \code{1} for Windows. #' #' @param nbrCoresDiffMeth a positive \code{integer}, the number of cores -#' to use for parallel differential methylation calculations.Parameter +#' to use for parallel differential methylation calculations. The parameter is #' used for both sites and tiles analysis. The parameter #' corresponds to the \code{num.cores} parameter in the package #' \code{methylKit}. @@ -334,27 +50,28 @@ runPermutationUsingRDSFile <- function(methylKitRDSFile, #' #' @param minReads a positive \code{integer} Bases and regions having lower #' coverage than this count are discarded. The parameter -#' correspond to the \code{lo.count} parameter in the package \code{methylKit}. +#' corresponds to the \code{lo.count} parameter in the package +#' \code{methylKit}. #' -#' @param minMethDiff a positive \code{double} betwwen [0,100], the absolute +#' @param minMethDiff a positive \code{double} between [0,100], the absolute #' value of methylation percentage change between cases and controls. The -#' parameter correspond to the \code{difference} parameter in +#' parameter corresponds to the \code{difference} parameter in #' the methylKit package. Default: \code{10}. #' -#' @param qvalue a positive \code{double} betwwen [0,1], the cutoff -#' for qvalue of differential methylation statistic. Default: \code{0.01}. +#' @param qvalue a positive \code{double} between [0,1], the cutoff +#' for qvalue of differential methylation statistics. Default: \code{0.01}. #' #' @param maxPercReads a \code{double} between [0,100], the percentile of read -#' counts that is going to be used as upper cutoff. Bases ore regions +#' counts that is going to be used as an upper cutoff. Bases or regions #' having higher -#' coverage than this percentile are discarded. Parameter used for both CpG -#' sites and tiles analysis. The parameter -#' correspond to the \code{hi.perc} parameter in the package \code{methylKit}. +#' coverage than this percentile are discarded. The parameter is used for +#' both CpG sites and tiles analysis. The parameter +#' corresponds to the \code{hi.perc} parameter in the package \code{methylKit}. #' Default: \code{99.9}. #' #' @param destrand a \code{logical}, when \code{TRUE} will merge reads on both #' strands of a CpG dinucleotide to provide better coverage. Only advised -#' when looking at CpG methylation. Parameter used for both CpG +#' when looking at CpG methylation. The parameter is used for both CpG #' sites and tiles analysis. #' Default: \code{FALSE}. #' @@ -379,166 +96,73 @@ runPermutationUsingRDSFile <- function(methylKitRDSFile, #' needed. When a value inferior or equal to zero is given, a random integer #' is used. Default: \code{-1}. #' -#' @return a \code{list} of class \code{} when a \code{runObservationAnalysis} -#' = \code{TRUE}; otherwise a \code{list}. The returned \code{list} -#' containing the following elements: -#' \itemize{ -#' \item \code{OBSERVATION} Only present when \code{runObservationAnalysis} = -#' \code{TRUE}, a \code{list} containing: -#' \itemize{ -#' \item \code{SITES} Only present when \code{type} = \code{"sites"} or -#' \code{"both"}, a \code{list} containing: -#' \itemize{ -#' \item\code{i2} a \code{list} containing: -#' \itemize{ -#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated sites between two consecutive generations. -#' The first element represents the intersection of the first and second -#' generations; the second element, the intersection of the second and third -#' generations; etc.. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated sites between two consecutive generations.The -#' first element represents the intersection of the first and second -#' generations; the second element, the intersection of the second and third -#' generations; etc.. -#' } -#' \item\code{iAll} a \code{list} containing: -#' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated sites between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number -#' of generations. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated sites between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of -#' generations. -#' } -#' } -#' \item \code{TILES} Only present when \code{type} = \code{"tiles"} or -#' \code{"both"}, a \code{list} containing: -#' \itemize{ -#' \item\code{i2} a \code{list} containing: -#' \itemize{ -#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated positions between two consecutive -#' generations. The first element represents the intersection of the -#' first and second generations; the second element, the intersection of -#' the second and third generations; etc.. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated positions between two consecutive -#' generations.The first element represents the intersection of the first and -#' second generations; the second element, the intersection of the second -#' and third generations; etc.. -#' } -#' \item\code{iAll} a \code{list} containing: -#' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated positions between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number -#' of generations. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated positions between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of -#' generations. -#' } -#' } -#' } -#' \item \code{PERMUTATION} a \code{list} -#' containing \code{nbrPermutations} entries. Each entry is -#' a \code{list} containing: -#' \itemize{ -#' \item \code{SITES} Only present when \code{type} = \code{"sites"} or -#' \code{"both"}, a \code{list} containing: -#' \itemize{ -#' \item\code{i2} a \code{list} containing: -#' \itemize{ -#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated sites between two consecutive generations. -#' The first element represents the intersection of the first and second -#' generations; the second element, the intersection of the second and third -#' generations; etc.. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated sites between two consecutive generations.The -#' first element represents the intersection of the first and second -#' generations; the second element, the intersection of the second and third -#' generations; etc.. -#' } -#' \item\code{iAll} a \code{list} containing: -#' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated sites between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number -#' of generations. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated sites between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of -#' generations. -#' } -#' } -#' \item \code{TILES} Only present when \code{type} = \code{"tiles"} or -#' \code{"both"}, a \code{list} containing: -#' \itemize{ -#' \item\code{i2} a \code{list} containing: -#' \itemize{ -#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated positions between two consecutive -#' generations. The first element represents the intersection of the -#' first and second generations; the second element, the intersection of -#' the second and third generations; etc.. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated positions between two consecutive -#' generations.The first element represents the intersection of the first and -#' second generations; the second element, the intersection of the second -#' and third generations; etc.. -#' } -#' \item\code{iAll} a \code{list} containing: -#' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated positions between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number -#' of generations. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated positions between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of -#' generations. -#' } -#' } -#' } -#' } +#' @param restartCalculation a \code{logical}, when \code{TRUE}, only +#' permutations that don't have an associated RDS result file are run. Useful +#' to restart a permutation analysis that has been interrupted. Beware that +#' the parameters have to be identical except for this one. +#' +#' @param saveInfoByGeneration a \code{logical}, when \code{TRUE}, the +#' information about differentially methylated sites and tiles for each +#' generation is saved in a RDS file. The information is saved in a different +#' file for each permutation. The files are saved in the directory specified +#' by the \code{outputDir} parameter. +#' +#' @return \code{0}. +#' +#' @seealso \code{\link{mergePermutationAndObservation}} for detail +#' description, in the Value section, of the +#' \code{methylInheritanceAllResults} object as +#' well as its \code{PERMUTATION} section. #' #' @examples #' -#' ## Load methyl information +#' ## Load methylKit information #' data(samplesForTransgenerationalAnalysis) #' -#' ## Run a permutation analysis -#' \dontrun{runPermutationUsingMethylKitInfo(methylKitInfo = -#' samplesForTransgenerationalAnalysis, type = "sites", -#' nbrPermutations = 3, vSeed = 221)} +#' ## Run a permutation analysis using the methylKit dataset +#' ## A real analysis would require a much higher number of permutations +#' runPermutation(methylKitData = samplesForTransgenerationalAnalysis, +#' outputDir = "test_01", runObservationAnalysis = FALSE, type = "sites", +#' nbrPermutations = 2, vSeed = 221) +#' +#' ## Get results +#' results_01 <- loadAllRDSResults(analysisResultsDir = NULL, +#' permutationResultsDir = "test_01", doingSites = TRUE, +#' doingTiles = FALSE) +#' +#' ## Remove results directory +#' if (dir.exists("test_01")) { +#' unlink("test_01", recursive = TRUE, force = TRUE) +#' } +#' +#' ## Path to a methylKit RDS file +#' methylFile <- system.file("extdata", "methylObj_001.RDS", +#' package = "methylInheritance") +#' +#' ## Run a permutation analysis using RDS file name +#' ## A real analysis would require a much higher number of permutations +#' runPermutation(methylKitData = methylFile, type = "tiles", +#' outputDir = "test_02", nbrPermutations = 2, minCovBasesForTiles = 10, +#' vSeed = 2001) +#' +#' ## Get results +#' results_02 <- loadAllRDSResults(analysisResultsDir = NULL, +#' permutationResultsDir = "test_02", doingSites = FALSE, +#' doingTiles = TRUE) +#' +#' ## Remove results directory +#' if (dir.exists("test_02")) { +#' unlink("test_02", recursive = TRUE, force = TRUE) +#' } #' #' @author Astrid Deschenes, Pascal Belleau #' @importFrom BiocParallel bplapply MulticoreParam SnowParam bptry bpok +#' @importFrom parallel mclapply nextRNGSubStream #' @importFrom methods new #' @export -runPermutationUsingMethylKitInfo <- function(methylKitInfo, +runPermutation <- function(methylKitData, type=c("both", "sites", "tiles"), - outputDir=NULL, + outputDir="output", runObservationAnalysis=TRUE, nbrPermutations=1000, nbrCores=1, @@ -551,21 +175,25 @@ runPermutationUsingMethylKitInfo <- function(methylKitInfo, minCovBasesForTiles=0, tileSize=1000, stepSize=1000, - vSeed=-1) { + vSeed=-1, + restartCalculation=FALSE, + saveInfoByGeneration=FALSE) { + + # Validate type value + type <- match.arg(type) ## Parameters validation - validateRunPermutationUsingMethylKitInfo(methylKitInfo = methylKitInfo, - type = type, outputDir = outputDir, - runObservedAnalysis = runObservationAnalysis, - nbrPermutations = nbrPermutations, - nbrCores = nbrCores, - nbrCoresDiffMeth = nbrCoresDiffMeth, - minReads = minReads, minMethDiff = minMethDiff, - qvalue = qvalue, maxPercReads = maxPercReads, - destrand = destrand, - minCovBasesForTiles = minCovBasesForTiles, - tileSize = tileSize, stepSize = stepSize, - vSeed = vSeed) + validateRunPermutation(methylKitData = methylKitData, + type = type, outputDir = outputDir, + runObservedAnalysis = runObservationAnalysis, + nbrPermutations = nbrPermutations, nbrCores = nbrCores, + nbrCoresDiffMeth = nbrCoresDiffMeth, minReads = minReads, + minMethDiff = minMethDiff, qvalue = qvalue, + maxPercReads = maxPercReads, destrand = destrand, + minCovBasesForTiles = minCovBasesForTiles, + tileSize = tileSize, stepSize = stepSize, vSeed = vSeed, + restartCalculation = restartCalculation, + saveInfoByGeneration = saveInfoByGeneration) ## Add last slash to path when absent if (!is.null(outputDir) && @@ -573,83 +201,56 @@ runPermutationUsingMethylKitInfo <- function(methylKitInfo, outputDir <- paste0(outputDir, "/") } + ## Load methylKit dataset when needed + if (is.character(methylKitData)) { + ## Extract information from RDS file + methylKitData <- readRDS(methylKitData) + } + ## Set vSeed value when negative seed is given if (vSeed <= -1) { tSeed <- as.numeric(Sys.time()) vSeed <- 1e8 * (tSeed - floor(tSeed)) } + RNGkind("L'Ecuyer-CMRG") set.seed(vSeed) - ## Extract information - nbGenerations <- length(methylKitInfo) - nbSamplesByGeneration <- sapply(methylKitInfo, length) - nbSamples <- sum(nbSamplesByGeneration) - allSamples <- unlist(methylKitInfo, recursive = FALSE) - - ## Create all permutations - permutationSamples <- t(replicate(nbrPermutations, sample(1:nbSamples))) - - ## Create list that will contain all information to run permutation - finalList <- vector("list", nbrPermutations) - - for (i in 1:nbrPermutations) { - ## Create list that will contain information for all generations - ## related to the same permutation analysis - permutationList <- vector("list", nbGenerations) - start <- 1 - for (j in 1:nbGenerations) { - end <- start + nbSamplesByGeneration[j] - 1 - samplePos <- permutationSamples[i, start:end] - treatment <- methylKitInfo[[j]]@treatment - newSampleList <- new("methylRawList", allSamples[samplePos], - treatment = treatment) - permutationList[[j]] <- newSampleList - start <- end + 1 - } - - finalList[[i]] <- list(sample = permutationList, id = i) - } - - rm(permutationSamples) - - if (nbrCores == 1) { - bpParam <- SnowParam() - } else { - bpParam <- MulticoreParam(workers = nbrCores) - } - - redoList <- list() - + ## Create directory for result files if (!is.null(outputDir)) { - doTiles <- any(type %in% c("tiles", "both")) - doSites <- any(type %in% c("sites", "both")) - createOutputDir(outputDir, doingSites = doSites, doingTiles = doTiles) + createOutputDir(outputDir, + doingSites = any(type %in% c("sites", "both")), + doingTiles = any(type %in% c("tiles", "both")), + saveInfoByGeneration = saveInfoByGeneration) } ## Call observation analysis if (runObservationAnalysis) { - result <- runObservationUsingMethylKitInfo(methylKitInfo = - methylKitInfo, - type = type, - outputDir = outputDir, - nbrCores = nbrCores, - nbrCoresDiffMeth = nbrCoresDiffMeth, - minReads = minReads, - minMethDiff = minMethDiff, - qvalue = qvalue, - maxPercReads = maxPercReads, - destrand = destrand, - minCovBasesForTiles = minCovBasesForTiles, - tileSize = tileSize, - stepSize = stepSize, - vSeed = vSeed) - } else { - result <- list() + runObservation(methylKitData = methylKitData, + type = type, + outputDir = outputDir, + nbrCoresDiffMeth = nbrCoresDiffMeth, + minReads = minReads, + minMethDiff = minMethDiff, + qvalue = qvalue, + maxPercReads = maxPercReads, + destrand = destrand, + minCovBasesForTiles = minCovBasesForTiles, + tileSize = tileSize, + stepSize = stepSize, + vSeed = vSeed, + restartCalculation = restartCalculation, + saveInfoByGeneration = saveInfoByGeneration) } + ## Upgrade seed + .Random.seed <- nextRNGSubStream(.Random.seed) + ## Call permutations in parallel mode - permutationResults <- bplapply(finalList, FUN = + if (nbrCores > 1) { + + mclapply(seq_len(nbrPermutations), FUN = runOnePermutationOnAllGenerations, + methylInfoForAllGenerations = methylKitData, type = type, outputDir = outputDir, nbrCoresDiffMeth = nbrCoresDiffMeth, @@ -661,33 +262,54 @@ runPermutationUsingMethylKitInfo <- function(methylKitInfo, minCovBasesForTiles = minCovBasesForTiles, tileSize = tileSize, stepSize = stepSize, - BPREDO = redoList, - BPPARAM = bpParam) - - result[["PERMUTATION"]] <- permutationResults - - if (runObservationAnalysis) { - class(result)<-"methylInheritanceAllResults" + restartCalculation = restartCalculation, + saveInfoByGeneration = saveInfoByGeneration, + mc.cores = nbrCores, + mc.preschedule = TRUE) + } else { + lapply(seq_len(nbrPermutations), FUN = + runOnePermutationOnAllGenerations, + methylInfoForAllGenerations = methylKitData, + type = type, + outputDir = outputDir, + nbrCoresDiffMeth = nbrCoresDiffMeth, + minReads = minReads, + minMethDiff = minMethDiff, + qvalue = qvalue, + maxPercReads = maxPercReads, + destrand = destrand, + minCovBasesForTiles = minCovBasesForTiles, + tileSize = tileSize, + stepSize = stepSize, + restartCalculation = restartCalculation, + saveInfoByGeneration = saveInfoByGeneration) } - return(result) + return(0) } -#' @title Run a differentially methylation analysis on each generation -#' present in a dataset +#' @title Run a differential methylation analysis on multi-generational +#' dataset #' -#' @description Run a differentially methylation analysis on each generation +#' @description Run a differential methylation analysis on each generation #' present in a dataset. The number of conserved differentially -#' methylated elements (sites, tile or both) is them calculated. The +#' methylated elements (sites, tile or both) between generations is +#' them calculated. The #' methylKit package is used to identify the differentially methylated #' elements. #' -#' @param methylKitInfo a \code{list} of \code{methylRawList} entries, each +#' The multi-generational dataset or the name of the RDS file that contains +#' the dataset can be used as input. +#' +#' The results can also be saved in RDS file (optional). +#' +#' @param methylKitData a \code{list} of \code{methylRawList} entries or the +#' name of the RDS file containing the list. Each #' \code{methylRawList} contains all the \code{methylRaw} entries related to #' one generation (first entry = first generation, second entry = second #' generation, etc..). The number of generations must correspond to the number -#' of entries in the \code{methylKitInfo}.At least 2 generations +#' of entries in the \code{methylKitData}.At least 2 generations #' must be present to calculate the conserved elements. More information can #' be found in the methylKit package. #' @@ -697,15 +319,11 @@ runPermutationUsingMethylKitInfo <- function(methylKitInfo, #' differentially methylated regions type="tiles". Default: "both". #' #' @param outputDir a string, the name of the directory that will contain -#' the results of the permutation or \code{NULL}. If the directory does not -#' exist, it will be created. When \code{NULL}, the results of the permutation -#' are not saved. Default: \code{NULL}. -#' -#' @param nbrCores a positive \code{integer}, the number of cores to use when -#' processing the analysis. Default: \code{1} and always \code{1} for Windows. +#' the results of the analysis. If the directory does not +#' exist, it will be created. Default: \code{"output"}. #' #' @param nbrCoresDiffMeth a positive \code{integer}, the number of cores -#' to use for parallel differential methylation calculations.Parameter +#' to use for parallel differential methylation calculations.The parameter is #' used for both sites and tiles analysis. The parameter #' corresponds to the \code{num.cores} parameter in the package #' \code{methylKit}. @@ -715,20 +333,20 @@ runPermutationUsingMethylKitInfo <- function(methylKitInfo, #' coverage than this count are discarded. The parameter #' correspond to the \code{lo.count} parameter in the package \code{methylKit}. #' -#' @param minMethDiff a positive \code{double} betwwen [0,100], the absolute +#' @param minMethDiff a positive \code{double} between [0,100], the absolute #' value of methylation percentage change between cases and controls. The -#' parameter correspond to the \code{difference} parameter in +#' parameter corresponds to the \code{difference} parameter in #' the methylKit package. Default: \code{10}. #' -#' @param qvalue a positive \code{double} betwwen [0,1], the cutoff -#' for qvalue of differential methylation statistic. Default: \code{0.01}. +#' @param qvalue a positive \code{double} between [0,1], the cutoff +#' for qvalue of differential methylation statistics. Default: \code{0.01}. #' #' @param maxPercReads a \code{double} between [0,100], the percentile of read -#' counts that is going to be used as upper cutoff. Bases ore regions +#' counts that is going to be used as an upper cutoff. Bases or regions #' having higher -#' coverage than this percentile are discarded. Parameter used for both CpG -#' sites and tiles analysis. The parameter -#' correspond to the \code{hi.perc} parameter in the package \code{methylKit}. +#' coverage than this percentile are discarded. The parameter is used for +#' both CpG sites and tiles analysis. The parameter +#' corresponds to the \code{hi.perc} parameter in the package \code{methylKit}. #' Default: \code{99.9}. #' #' @param destrand a \code{logical}, when \code{TRUE} will merge reads on both @@ -758,114 +376,76 @@ runPermutationUsingMethylKitInfo <- function(methylKitInfo, #' needed. When a value inferior or equal to zero is given, a random integer #' is used. Default: \code{-1}. #' -#' @return a \code{list} containing the following elements: -#' \itemize{ -#' \item \code{OBSERVATION} a \code{list} containing the following elements: -#' \itemize{ -#' \item \code{SITES} Only present when \code{type} = \code{"sites"} or -#' \code{"both"}, a \code{list} containing: -#' \itemize{ -#' \item\code{i2} a \code{list} containing: -#' \itemize{ -#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated sites between two consecutive generations. -#' The first element represents the intersection of the first and second -#' generations; the second element, the intersection of the second and third -#' generations; etc.. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated sites between two consecutive generations.The -#' first element represents the intersection of the first and second -#' generations; the second element, the intersection of the second and third -#' generations; etc.. -#' } -#' \item\code{iAll} a \code{list} containing: -#' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated sites between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number -#' of generations. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated sites between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of -#' generations. -#' } -#' } -#' \item \code{TILES} Only present when \code{type} = \code{"tiles"} or -#' \code{"both"}, a \code{list} containing: -#' itemize{ -#' \item\code{i2} a \code{list} containing: -#' \itemize{ -#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated positions between two consecutive -#' generations. The first element represents the intersection of the -#' first and second generations; the second element, the intersection of -#' the second and third generations; etc.. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated positions between two consecutive -#' generations.The first element represents the intersection of the first and -#' second generations; the second element, the intersection of the second -#' and third generations; etc.. -#' } -#' \item\code{iAll} a \code{list} containing: -#' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated positions between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number -#' of generations. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated positions between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of -#' generations. -#' } -#' } -#' } -#' } +#' @param restartCalculation a \code{logical}, when \code{TRUE}, only +#' permutations that don't have a RDS result final are run. Useful +#' to restart a permutation analysis that has been interrupted. Beware that +#' the parameters have to be identical except for this one. +#' +#' @param saveInfoByGeneration a \code{logical}, when \code{TRUE}, the +#' information about differentially methylated sites and tiles for each +#' generation is saved in a RDS file. The files are saved in the directory +#' specified by the \code{outputDir} parameter. +#' +#' @return \code{0}. +#' +#' @seealso \code{\link{mergePermutationAndObservation}} for detail +#' description, in the Value section, of the \code{OBSERVATION} section of the +#' \code{methylInheritanceAllResults} object. #' #' @examples #' -#' ## Load methyl information +#' ## Load methylation information #' data(samplesForTransgenerationalAnalysis) #' -#' ## Run a permutation analysis -#' \dontrun{runObservationUsingMethylKitInfo(methylKitInfo = -#' samplesForTransgenerationalAnalysis, type = "sites", vSeed = 221)} +#' ## Run an observation analysis +#' runObservation(methylKitData = samplesForTransgenerationalAnalysis, +#' outputDir = "test", type = "sites", vSeed = 221) +#' +#' ## Load the results +#' results <- loadAllRDSResults(analysisResultsDir = "test", +#' permutationResultsDir = NULL, doingSites = TRUE, doingTiles = FALSE) +#' +#' ## Print the results +#' results +#' +#' ## Remove directory +#' if (dir.exists("test")) { +#' unlink("test", recursive = TRUE, force = FALSE) +#' } #' #' @author Astrid Deschenes, Pascal Belleau #' @export -runObservationUsingMethylKitInfo <- function(methylKitInfo, - type=c("both", "sites", "tiles"), - outputDir=NULL, - nbrCores=1, - nbrCoresDiffMeth=1, - minReads=10, - minMethDiff=10, - qvalue=0.01, - maxPercReads=99.9, - destrand=FALSE, - minCovBasesForTiles=0, - tileSize=1000, - stepSize=1000, - vSeed=-1) { +runObservation <- function(methylKitData, + type=c("both", "sites", "tiles"), + outputDir="output", + nbrCoresDiffMeth=1, + minReads=10, + minMethDiff=10, + qvalue=0.01, + maxPercReads=99.9, + destrand=FALSE, + minCovBasesForTiles=0, + tileSize=1000, + stepSize=1000, + vSeed=-1, + restartCalculation=FALSE, + saveInfoByGeneration=FALSE) { + + # Validate type value + type <- match.arg(type) ## Parameters validation - validateRunObservationUsingMethylKitInfo(methylKitInfo = methylKitInfo, + validateRunObservation(methylKitData = methylKitData, type = type, outputDir = outputDir, - nbrCores = nbrCores, nbrCoresDiffMeth = nbrCoresDiffMeth, minReads = minReads, minMethDiff = minMethDiff, qvalue = qvalue, maxPercReads = maxPercReads, destrand = destrand, minCovBasesForTiles = minCovBasesForTiles, tileSize = tileSize, - stepSize = stepSize, vSeed = vSeed) + stepSize = stepSize, vSeed = vSeed, + restartCalculation = restartCalculation, + saveInfoByGeneration = saveInfoByGeneration) ## Add last slash to path when absent if (!is.null(outputDir) && @@ -873,282 +453,239 @@ runObservationUsingMethylKitInfo <- function(methylKitInfo, outputDir <- paste0(outputDir, "/") } + ## Load methylKit dataset when needed + if (is.character(methylKitData)) { + ## Extract information from RDS file + methylKitData <- readRDS(methylKitData) + } + ## Set vSeed value when negative seed is given if (vSeed <= -1) { tSeed <- as.numeric(Sys.time()) vSeed <- 1e8 * (tSeed - floor(tSeed)) } + RNGkind("L'Ecuyer-CMRG") set.seed(vSeed) - methylInfo <- list(sample = methylKitInfo, id = 0) + methylInfo <- list(sample = methylKitData, id = 0) if (!is.null(outputDir)) { doTiles <- any(type %in% c("tiles", "both")) doSites <- any(type %in% c("sites", "both")) - createOutputDir(outputDir, doingSites = doSites, doingTiles = doTiles) + createOutputDir(outputDir, doingSites = doSites, doingTiles = doTiles, + saveInfoByGeneration = saveInfoByGeneration) } ## Extract information - observed <- runOnePermutationOnAllGenerations(methylInfoForAllGenerations = - methylInfo, - type = type, outputDir = outputDir, - nbrCoresDiffMeth = nbrCoresDiffMeth, - minReads = minReads, - minMethDiff = minMethDiff, - qvalue = qvalue, - maxPercReads = maxPercReads, - destrand = destrand, - minCovBasesForTiles = minCovBasesForTiles, - tileSize = tileSize, - stepSize = stepSize) - - ## Create final returned list - result <- list() - result[["OBSERVATION"]] <- observed + runOnePermutationOnAllGenerations(id = 0, + methylInfoForAllGenerations = methylKitData, + type = type, outputDir = outputDir, + nbrCoresDiffMeth = nbrCoresDiffMeth, + minReads = minReads, + minMethDiff = minMethDiff, + qvalue = qvalue, + maxPercReads = maxPercReads, + destrand = destrand, + minCovBasesForTiles = minCovBasesForTiles, + tileSize = tileSize, + stepSize = stepSize, + restartCalculation = restartCalculation, + saveInfoByGeneration = saveInfoByGeneration) - return(result) + return(0) } -#' @title Run a differentially methylation analysis on each generation -#' present in a dataset -#' -#' @description Run a differentially methylation analysis on each generation -#' present in a dataset. The number of conserved differentially -#' methylated elements (sites, tile or both) is them calculated. The -#' methylKit package is used to identify the differentially methylated -#' elements. -#' -#' @param methylKitRDSFile a string, the name of the RDS file containing the -#' methylKit objet used for the permutation analysis. The RDS file must -#' hold a \code{list} of \code{methylRawList} entries, each -#' \code{methylRawList} contains all the \code{methylRaw} entries related to -#' one generation (first entry = first generation, second entry = second -#' generation, etc..). The number of generations must correspond to the number -#' of entries in the \code{methylKitInfo}.At least 2 generations -#' must be present to do a permutation analysis. More information can be found -#' in the methylKit package. -#' -#' @param type One of the "sites","tiles" or "both" strings. Specifies the type -#' of differentially methylated elements should be returned. For -#' retrieving differentially methylated bases type="sites"; for -#' differentially methylated regions type="tiles". Default: "both". -#' -#' @param outputDir a string, the name of the directory that will contain -#' the results of the permutation or \code{NULL}. If the directory does not -#' exist, it will be created. When \code{NULL}, the results of the permutation -#' are not saved. Default: \code{NULL}. -#' -#' @param nbrCores a positive \code{integer}, the number of cores to use when -#' processing the analysis. Default: \code{1} and always \code{1} for Windows. -#' -#' @param nbrCoresDiffMeth a positive \code{integer}, the number of cores -#' to use for parallel differential methylation calculations.Parameter -#' used for both sites and tiles analysis. The parameter -#' corresponds to the \code{num.cores} parameter in the package -#' \code{methylKit}. -#' Default: \code{1} and always \code{1} for Windows. + +#' @title Load all RDS files created by the permutation and observation +#' analysis #' -#' @param minReads a positive \code{integer} Bases and regions having lower -#' coverage than this count are discarded. The parameter -#' correspond to the \code{lo.count} parameter in the package \code{methylKit}. +#' @description Load all RDS files created by the permutation and +#' observation analysis. The function +#' returns an object of \code{class} "methylInheritanceAllResults" that holds +#' all the pertinent information. #' -#' @param minMethDiff a positive \code{double} betwwen [0,100], the absolute -#' value of methylation percentage change between cases and controls. The -#' parameter correspond to the \code{difference} parameter in -#' the methylKit package. Default: \code{10}. +#' @param analysisResultsDir a \code{character} string, the path to the +#' directory that contains the analysis results. The path can be the same as +#' for the \code{permutationResultsDir} parameter. When \code{NULL}, the +#' observation results are not loaded. Default = \code{NULL}. #' -#' @param qvalue a positive \code{double} betwwen [0,1], the cutoff -#' for qvalue of differential methylation statistic. Default: \code{0.01}. +#' @param permutationResultsDir a \code{character} string, the path to the +#' directory that contains the permutation results. The path can be the same +#' as for the \code{analysisResultsDir} parameter. When \code{NULL}, the +#' permutation results are not loaded. Default = \code{NULL}. #' -#' @param maxPercReads a \code{double} between [0,100], the percentile of read -#' counts that is going to be used as upper cutoff. Bases ore regions -#' having higher -#' coverage than this percentile are discarded. Parameter used for both CpG -#' sites and tiles analysis. The parameter -#' correspond to the \code{hi.perc} parameter in the package \code{methylKit}. -#' Default: \code{99.9}. +#' @param doingSites a \code{logical}, the data related to differentially +#' methylated sites are loaded when +#' \code{doingSites} = \code{TRUE}. Default: \code{TRUE}. #' -#' @param destrand a \code{logical}, when \code{TRUE} will merge reads on both -#' strands of a CpG dinucleotide to provide better coverage. Only advised -#' when looking at CpG methylation. Parameter used for both CpG -#' sites and tiles analysis. -#' Default: \code{FALSE}. +#' @param doingTiles a \code{logical}, the data related to differentially +#' methylated tiles are loaded when +#' \code{doingTiles} = \code{TRUE}. Default: \code{TRUE}. #' -#' @param minCovBasesForTiles a non-negative \code{integer}, the minimum -#' number of bases to be covered in a given tiling window. The parameter -#' corresponds to the \code{cov.bases} parameter in the package -#' \code{methylKit}. -#' Only used when \code{doingTiles} = -#' \code{TRUE}. Default: \code{0}. +#' @param maxID \code{NA} or a positive \code{integer}, the maximum +#' identification number of the permutation files to be loaded. When \code{NA}, +#' all files present in the directory are loaded. Default: \code{NA}. #' -#' @param tileSize a positive \code{integer}, the size of the tiling window. -#' The parameter corresponds to the \code{win.size} parameter in -#' the package \code{methylKit}. Only -#' used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}. +#' @return a \code{list} of class \code{methylInheritanceAllResults} +#' containing the result of the observation analysis as well as the results +#' of all the permutations. #' -#' @param stepSize a positive \code{integer}, the step size of tiling windows. -#' The parameter corresponds to the \code{stepSize} parameter in -#' the package \code{methylKit}. Only -#' used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}. +#' @seealso \code{\link{mergePermutationAndObservation}} for detail +#' description, in the Value section, of the +#' \code{methylInheritanceAllResults} object. #' -#' @param vSeed a \code{integer}, a seed used when reproducible results are -#' needed. When a value inferior or equal to zero is given, a random integer -#' is used. Default: \code{-1}. +#' @examples #' -#' @return @return a \code{list} containing the following elements: -#' \itemize{ -#' \item \code{SITES} Only present when \code{type} = \code{"sites"} or -#' \code{"both"}, a \code{list} containing: -#' \itemize{ -#' \item\code{i2} a \code{list} containing: -#' \itemize{ -#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated sites between two consecutive generations. -#' The first element represents the intersection of the first and second -#' generations; the second element, the intersection of the second and third -#' generations; etc.. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated sites between two consecutive generations.The -#' first element represents the intersection of the first and second -#' generations; the second element, the intersection of the second and third -#' generations; etc.. -#' } -#' \item\code{iAll} a \code{list} containing: -#' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated sites between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number -#' of generations. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated sites between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of -#' generations. -#' } -#' } -#' \item \code{TILES} Only present when \code{type} = \code{"tiles"} or -#' \code{"both"}, a \code{list} containing: -#' \itemize{ -#' \item\code{i2} a \code{list} containing: -#' \itemize{ -#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated positions between two consecutive -#' generations. The first element represents the intersection of the -#' first and second generations; the second element, the intersection of -#' the second and third generations; etc.. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated positions between two consecutive -#' generations.The first element represents the intersection of the first and -#' second generations; the second element, the intersection of the second -#' and third generations; etc.. -#' } -#' \item\code{iAll} a \code{list} containing: -#' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -#' hyper differentially methylated positions between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number -#' of generations. -#' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -#' hypo differentially methylated positions between three or more consecutive -#' generations. The first element represents the intersection of the first -#' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of -#' generations. -#' } -#' } -#' } +#' ## Get the name of the directory where files are stored +#' filesDir <- system.file("extdata", "TEST", package="methylInheritance") #' -#' @examples +#' ## Load information from files +#' results <- loadAllRDSResults(analysisResultsDir = filesDir, +#' permutationResultsDir = filesDir, doingSites = TRUE, doingTiles = TRUE) #' -#' ## Path to a methylKit RDS file -#' methylFile <- dir(system.file("extdata", package = "methylInheritance"), -#' pattern = "methylObj_001.RDS", full.names = TRUE) +#' ## Print the observation results +#' results #' -#' ## Run a permutation analysis -#' \dontrun{runObservationUsingRDSFile(methylKitRDSFile = methylFile, -#' type = "sites", minReads = 8, minMethDiff = 5, -#' vSeed = 2001)} +#' ## Access the results for the first permutation only for sites +#' results$PERMUTATION[[1]]$SITES #' #' @author Astrid Deschenes, Pascal Belleau +#' @importFrom rebus number_range #' @export -runObservationUsingRDSFile <- function(methylKitRDSFile, - type=c("both", "sites", "tiles"), - outputDir=NULL, - nbrCores=1, - nbrCoresDiffMeth=1, - minReads=10, - minMethDiff=10, - qvalue=0.01, - maxPercReads=99.9, - destrand=FALSE, - minCovBasesForTiles=0, - tileSize=1000, - stepSize=1000, - vSeed=-1) { - - ## Validate that methylKitRDSFile is an existing file - if (!file.exists(methylKitRDSFile)) { - stop(paste0("The file \"", methylKitRDSFile, "\" does not exist.")) +loadAllRDSResults <- function(analysisResultsDir, + permutationResultsDir, + doingSites=TRUE, doingTiles=FALSE, + maxID = NA) { + + ## Validate parameters + if (!is.na(maxID) && !is.numeric(maxID) && maxID > 0) { + stop("maxID must be NA or a positive integer") + } + + ## Add last slash to analysisResultsDIR when absent + if (!is.null(analysisResultsDir) && + (substr(analysisResultsDir, nchar(analysisResultsDir), + nchar(analysisResultsDir)) != "/")) { + analysisResultsDir <- paste0(analysisResultsDir, "/") + } + + ## Add last slash to permutationResultsDIR when absent + if (!is.null(permutationResultsDir) && + (substr(permutationResultsDir, nchar(permutationResultsDir), + nchar(permutationResultsDir)) != "/")) { + permutationResultsDir <- paste0(permutationResultsDir, "/") + } + + result<-list() + + if (!is.na(maxID)) { + rxRange <- suppressWarnings(number_range(1, maxID)) + newRange <- gsub(pattern = "\\?\\:", replacement = "", + toString(rxRange)) + filePattern <- paste0("[^[:digit:]]", newRange, ".RDS") + } else { + filePattern <- "[[:digit:]].RDS" + } + + ## SITES + if (doingSites) { + if (!is.null(analysisResultsDir)) { + analysisResults <- readRDS(file = paste0(analysisResultsDir, + "SITES/SITES_observed_results.RDS")) + analysisStruct <- createDataStructure(interGenerationGR = + analysisResults) + result[["OBSERVATION"]][["SITES"]] <- analysisStruct + } + + if (!is.null(permutationResultsDir)) { + filesInDir <- list.files(path = paste0(permutationResultsDir, + "SITES/"), + pattern = filePattern, all.files = FALSE, + full.names = TRUE, recursive = FALSE, + ignore.case = FALSE, include.dirs = FALSE, + no.. = FALSE) + + sitesPerm <- lapply(filesInDir, FUN = function(x) { + readRDS(file = x)}) + + t <- lapply(sitesPerm, FUN = function(x) { + struct <- createDataStructure(interGenerationGR = x) + res <- list("SITES" = struct) + return(res)}) + + result[["PERMUTATION"]] <- t + } + } + + ## TILES + if (doingTiles) { + if (!is.null(analysisResultsDir)) { + analysisResults <- readRDS(file = paste0(analysisResultsDir, + "TILES/TILES_observed_results.RDS")) + analysisStruct <- createDataStructure(interGenerationGR = + analysisResults) + result[["OBSERVATION"]][["TILES"]] <- analysisStruct + } + + if (!is.null(permutationResultsDir)) { + filesInDir <- list.files(path = paste0(permutationResultsDir, + "TILES/"), + pattern = filePattern, all.files = FALSE, + full.names = TRUE, recursive = FALSE, + ignore.case = FALSE, include.dirs = FALSE, + no.. = FALSE) + + tilesPerm <- lapply(filesInDir, FUN = function(x) { + readRDS(file = x)}) + + t <- lapply(tilesPerm, FUN = function(x) { + struct <- createDataStructure(interGenerationGR = x) + res <- list("TILES" = struct) + return(res)}) + + if (!doingSites) { + result[["PERMUTATION"]] <- t + } else { + for (i in seq_len(length(result[["PERMUTATION"]]))) { + result[["PERMUTATION"]][[i]]$TILES <- t[[i]]$TILES + } + } + } } - ## Extract information from RDS file - methylInfo <- readRDS(methylKitRDSFile) - - ## Call permutation analysis with the methylInfo object as an parameter - result <- runObservationUsingMethylKitInfo(methylKitInfo = methylInfo, - type = type, - outputDir = outputDir, - nbrCores = nbrCores, - nbrCoresDiffMeth = nbrCoresDiffMeth , - minReads = minReads, - minMethDiff = minMethDiff, - qvalue = qvalue, - maxPercReads = maxPercReads, - destrand = destrand, - minCovBasesForTiles = minCovBasesForTiles, - tileSize = tileSize, stepSize = stepSize, - vSeed = vSeed) + class(result)<-"methylInheritanceAllResults" return(result) } -#' @title Load all RDS files created by the permutation and observation -#' analysis -#' -#' @description Load all RDS files created by the permutation and -#' observation analysis. The function -#' returns an object of \code{class} "methylInheritanceAllResults" that holds -#' all the pertinent information. -#' -#' @param analysisResultsDir a \code{character} string, the path to the -#' directory that contains the analysis results. The path can be the same that -#' for the \code{permutatioNResultsDir} parameter. +#' @title Merge the permutation results with the observation results. #' -#' @param permutationResultsDir a \code{character} string, the path to the -#' directory that contains the permutation results. The path can be the same -#' that for the \code{analysisResultsDir} parameter. +#' @description Merge the permutation results with the observation results. +#' The merging is only needed when permutation and observation have been +#' processed separately. The returned value is a +#' \code{methylInheritanceAllResults} object that can be used by +#' the \code{extractInfo} function. #' -#' @param doingSites a \code{logical}, the data related to differentially -#' methylated sites are loaded when -#' \code{doingSites} = \code{TRUE}. Default: \code{TRUE}. +#' @param permutationResults a \code{list} with 1 entry called +#' \code{PERMUTATION}. The \code{PERMUTATION} entry is a \code{list} with +#' a number of entries corresponding +#' to the number of permutations that have been processed. Each entry contains +#' the result of one permutation. #' -#' @param doingTiles a \code{logical}, the data related to differentially -#' methylated tiles are loaded when -#' \code{doingTiles} = \code{TRUE}. Default: \code{TRUE}. +#' @param observationResults a \code{list} with 1 entry called +#' \code{OBSERVATION}. The \code{OBSERVATION} entry is a \code{list} containing +#' the result obtained +#' with the observed dataset (not shuffled). #' -#' @return a \code{list} of \code{class} "methylInheritanceAllResults" -#' containing the following elements: +#' @return a \code{list} of class \code{methylInheritanceAllResults} with +#' 2 entries. The 2 entries are: #' \itemize{ -#' \item \code{OBSERVATION}, a \code{list} that contains one or two entries. -#' The possible entries are: +#' \item \code{PERMUTATION} \code{list} with a number of entries corresponding +#' to the number of permutations that have been processed. Each entry contains +#' the result of one permutation.The elements in each entry are: #' \itemize{ -#' \item \code{SITES} The results of an analysis by sites, +#' \item \code{SITES} Only present when a sites analysis has been achieved, #' a \code{list} containing: #' \itemize{ #' \item\code{i2} a \code{list} containing: @@ -1157,31 +694,31 @@ runObservationUsingRDSFile <- function(methylKitRDSFile, #' hyper differentially methylated sites between two consecutive generations. #' The first element represents the intersection of the first and second #' generations; the second element, the intersection of the second and third -#' generations; etc.. +#' generations; etc. #' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved #' hypo differentially methylated sites between two consecutive generations.The #' first element represents the intersection of the first and second #' generations; the second element, the intersection of the second and third -#' generations; etc.. +#' generations; etc. #' } #' \item\code{iAll} a \code{list} containing: #' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved +#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved #' hyper differentially methylated sites between three or more consecutive #' generations. The first element represents the intersection of the first #' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number +#' generations; etc.The number of entries depends on the number #' of generations. #' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved #' hypo differentially methylated sites between three or more consecutive #' generations. The first element represents the intersection of the first #' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of +#' generations; etc. The number of entries depends on the number of #' generations. #' } #' } -#' \item \code{TILES} The results of an ananlysis by tiles, a -#' \code{list} containing: +#' \item \code{TILES} Only present when a tiles analysis has been achieved, +#' a \code{list} containing: #' \itemize{ #' \item\code{i2} a \code{list} containing: #' \itemize{ @@ -1189,12 +726,12 @@ runObservationUsingRDSFile <- function(methylKitRDSFile, #' hyper differentially methylated positions between two consecutive #' generations. The first element represents the intersection of the #' first and second generations; the second element, the intersection of -#' the second and third generations; etc.. +#' the second and third generations; etc. #' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved #' hypo differentially methylated positions between two consecutive #' generations.The first element represents the intersection of the first and #' second generations; the second element, the intersection of the second -#' and third generations; etc.. +#' and third generations; etc. #' } #' \item\code{iAll} a \code{list} containing: #' \itemize{ @@ -1202,24 +739,23 @@ runObservationUsingRDSFile <- function(methylKitRDSFile, #' hyper differentially methylated positions between three or more consecutive #' generations. The first element represents the intersection of the first #' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number +#' generations; etc. The number of entries depends on the number #' of generations. #' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved #' hypo differentially methylated positions between three or more consecutive #' generations. The first element represents the intersection of the first #' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of +#' generations; etc.The number of entries depends on the number of #' generations. #' } #' } #' } -#' \item \code{PERMUTATION} a \code{list} -#' containing multiple entries. Each entry is the result of one permutation -#' analysis and contains -#' a \code{list} with one or two entries. The possible entries are: +#' \item \code{OBSERVATION} a \code{list} containing +#' the result obtained with the observed dataset (not shuffled). The +#' elements are: #' \itemize{ -#' \item \code{SITES} The results of an analysis by sites, a -#' \code{list} containing: +#' \item \code{SITES} Only present when a sites analysis has been achieved, +#' a \code{list} containing: #' \itemize{ #' \item\code{i2} a \code{list} containing: #' \itemize{ @@ -1227,12 +763,12 @@ runObservationUsingRDSFile <- function(methylKitRDSFile, #' hyper differentially methylated sites between two consecutive generations. #' The first element represents the intersection of the first and second #' generations; the second element, the intersection of the second and third -#' generations; etc.. +#' generations; etc. #' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved #' hypo differentially methylated sites between two consecutive generations.The #' first element represents the intersection of the first and second #' generations; the second element, the intersection of the second and third -#' generations; etc.. +#' generations; etc. #' } #' \item\code{iAll} a \code{list} containing: #' \itemize{ @@ -1240,17 +776,17 @@ runObservationUsingRDSFile <- function(methylKitRDSFile, #' hyper differentially methylated sites between three or more consecutive #' generations. The first element represents the intersection of the first #' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number +#' generations; etc.The number of entries depends on the number #' of generations. #' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved #' hypo differentially methylated sites between three or more consecutive #' generations. The first element represents the intersection of the first #' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of +#' generations; etc. The number of entries depends on the number of #' generations. #' } #' } -#' \item \code{TILES} The results of an analysis by tiles, +#' \item \code{TILES} Only present when a tiles analysis has been achieved, #' a \code{list} containing: #' \itemize{ #' \item\code{i2} a \code{list} containing: @@ -1259,26 +795,26 @@ runObservationUsingRDSFile <- function(methylKitRDSFile, #' hyper differentially methylated positions between two consecutive #' generations. The first element represents the intersection of the #' first and second generations; the second element, the intersection of -#' the second and third generations; etc.. +#' the second and third generations; etc. #' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved #' hypo differentially methylated positions between two consecutive #' generations.The first element represents the intersection of the first and #' second generations; the second element, the intersection of the second -#' and third generations; etc.. +#' and third generations; etc. #' } #' \item\code{iAll} a \code{list} containing: #' \itemize{ -#'\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved +#' \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved #' hyper differentially methylated positions between three or more consecutive #' generations. The first element represents the intersection of the first #' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number +#' generations; etc. The number of entries depends on the number #' of generations. #' \item \code{HYPO} a \code{list} of \code{integer}, the number of conserved #' hypo differentially methylated positions between three or more consecutive #' generations. The first element represents the intersection of the first #' three generations; the second element, the intersection of the first fourth -#' generations; etc..The number of entries depends of the number of +#' generations; etc.The number of entries depends on the number of #' generations. #' } #' } @@ -1287,137 +823,14 @@ runObservationUsingRDSFile <- function(methylKitRDSFile, #' #' @examples #' -#' ## Get the name of the directory where files are stored -#' filesDir <- dir(system.file("extdata", package = "methylInheritance"), -#' pattern = "TEST", full.names = TRUE) -#' -#' ## Load information from files -#' results <- loadAllRDSResults(analysisResultsDir = filesDir, -#' permutationResultsDir = filesDir, doingSites = TRUE, doingTiles = TRUE) -#' -#' @author Astrid Deschenes, Pascal Belleau -#' @export -loadAllRDSResults <- function(analysisResultsDir, - permutationResultsDir, - doingSites=TRUE, doingTiles=FALSE) { - - ## Add last slash to analysisResultsDIR when absent - if (!is.null(analysisResultsDir) && - (substr(analysisResultsDir, nchar(analysisResultsDir), - nchar(analysisResultsDir)) != "/")) { - analysisResultsDir <- paste0(analysisResultsDir, "/") - } - - ## Add last slash to permutationResultsDIR when absent - if (!is.null(permutationResultsDir) && - (substr(permutationResultsDir, nchar(permutationResultsDir), - nchar(permutationResultsDir)) != "/")) { - permutationResultsDir <- paste0(permutationResultsDir, "/") - } - - result<-list() - - ## SITES - if (doingSites) { - analysisResults <- readRDS(file = paste0(analysisResultsDir, - "SITES/SITES_observed_results.RDS")) - analysisStruct <- createDataStructure(interGenerationGR = - analysisResults) - result[["OBSERVATION"]][["SITES"]] <- analysisStruct - - filesInDir <- list.files(path = paste0(analysisResultsDir, - "SITES/"), - pattern = "[[:digit:]].RDS", all.files = FALSE, - full.names = TRUE, recursive = FALSE, - ignore.case = FALSE, include.dirs = FALSE, - no.. = FALSE) - - sitesPerm <- lapply(filesInDir, FUN = function(x) {readRDS(file = x)}) - - t <- lapply(sitesPerm, FUN = function(x) { - struct <- createDataStructure(interGenerationGR = x) - res <- list("SITES" = struct) - return(res)}) - - result[["PERMUTATION"]] <- t - } - - ## TILES - if (doingTiles) { - analysisResults <- readRDS(file = paste0(permutationResultsDir, - "TILES/TILES_observed_results.RDS")) - analysisStruct <- createDataStructure(interGenerationGR = - analysisResults) - result[["OBSERVATION"]][["TILES"]] <- analysisStruct - - filesInDir <- list.files(path = paste0(permutationResultsDir, - "TILES/"), - pattern = "[[:digit:]].RDS", all.files = FALSE, - full.names = TRUE, recursive = FALSE, - ignore.case = FALSE, include.dirs = FALSE, - no.. = FALSE) - - tilesPerm <- lapply(filesInDir, FUN = function(x) {readRDS(file = x)}) - - t <- lapply(tilesPerm, FUN = function(x) { - struct <- createDataStructure(interGenerationGR = x) - res <- list("TILES" = struct) - return(res)}) - if (!doingSites) { - result[["PERMUTATION"]] <- t - } else { - for (i in 1:length(result[["PERMUTATION"]])) { - result[["PERMUTATION"]][[i]]$TILES <- t[[i]]$TILES - } - } - - } - - class(result)<-"methylInheritanceAllResults" - - return(result) -} - - -#' @title Merge the permutation results with the observation results. -#' -#' @description Merge the permutation results with the observation results. -#' The merging is only needed when permutation and observation have been -#' processed separatly. The returned value is a -#' \code{methylInheritanceAllResults} object that can be used by -#' the \code{extractInfo} function. -#' -#' @param permutationResults a \code{list} with 1 entry called -#' \code{PERMUTATION}. The \code{PERMUTATION} entry is a \code{list} with -#' a number of entries corresponding -#' to the number of permutations that have been processed. Each entry contains -#' the result of one permutation. -#' -#' @param observationResults a \code{list} with 1 entry called -#' \code{OBSERVATION}. The \code{OBSERVATION} entry is a \code{list} containing -#' the result obtained -#' with the observed dataset (not permutated). -#' -#' @return a \code{list} of class \code{methylInheritanceAllResults} with -#' 2 entries. The 2 entries are: -#' \itemize{ -#' \item \code{PERMUTATION} \code{list} with a number of entries corresponding -#' to the number of permutations that have been processed. Each entry contains -#' the result of one permutation. -#' \item \code{OBSERVATION} a \code{list} containing the result obtained -#' with the observed dataset (not permutated). -#' } -#' -#' @examples -#' #' ## Create a observation result #' observed <- list() #' observed[["OBSERVATION"]] <- list() #' observed[["OBSERVATION"]][["SITES"]] <- list() #' observed[["OBSERVATION"]][["SITES"]][["i2"]] <- list(HYPER = list(11, 10), -#' HYPO = list(13, 12)) +#' HYPO = list(13, 12)) #' observed[["OBSERVATION"]][["SITES"]][["iAll"]] <- list(HYPER = list(1), -#' HYPO = list(3)) +#' HYPO = list(3)) #' #' ## Create a permutation result containing only 1 permutation result #' ## Real perumtations results would have more entries @@ -1426,13 +839,13 @@ loadAllRDSResults <- function(analysisResultsDir, #' permutated[["PERMUTATION"]][[1]] <- list() #' permutated[["PERMUTATION"]][[1]][["SITES"]] <- list() #' permutated[["PERMUTATION"]][[1]][["SITES"]][["i2"]] <- list(HYPER = -#' list(11, 12), HYPO = list(8, 11)) +#' list(11, 12), HYPO = list(8, 11)) #' permutated[["PERMUTATION"]][[1]][["SITES"]][["iAll"]] <- list(HYPER = -#' list(0), HYPO = list(1)) +#' list(0), HYPO = list(1)) #' #' ## Merge permutation and observation results #' mergePermutationAndObservation(permutationResults = permutated, -#' observationResults = observed) +#' observationResults = observed) #' #' @author Astrid Deschenes, Pascal Belleau #' @export @@ -1458,19 +871,18 @@ mergePermutationAndObservation <- function(permutationResults, #' #' @description Extract the information specific to a subsection of the #' permutation analysis. The extracted information will be specific to one -#' type of differentially methylation analysis (tiles or sites), to one type +#' type of differential methylation analysis (tiles or sites), to one type #' of intersection (two consecutive generation or more) and to one specific #' group of generations. #' #' @param allResults a \code{list} of class \code{methylInheritanceAllResults} #' as created by the -#' \code{runPermutationUsingMethylKitInfo} or the -#' \code{runPermutationUsingRDSFile} functions. The \code{list} must contain +#' \code{runPermutation} function. The \code{list} must contain #' two entries : \code{"PERMUTATION"} and \code{"OBSERVATION"}. The #' \code{"PERMUTATION"} \code{list} must contain all results from all #' permutations while #' the \code{"OBSERVATION"} \code{list} must contain the result obtained with -#' the observed dataset (not permutated). +#' the observed dataset (not shuffled). #' #' @param type One of the \code{"sites"} or \code{"tiles"} strings. #' Specifies the type @@ -1487,34 +899,39 @@ mergePermutationAndObservation <- function(permutationResults, #' Default: \code{"i2"}. #' #' @param position a positive \code{integer}, the position in the \code{list} -#' where the information will be extracted. +#' where the information will be extracted. Default=\code{1}. #' #' @return a \code{data.frame} #' containing the observation results (using real -#' data) and the permutation results (using permutated data). Both hyper and +#' data) and the permutation results (using shuffled data). Both hyper and #' hypo differentially conserved methylation results are present. #' #' @examples #' #' ## Get the name of the directory where files are stored -#' filesDir <- dir(system.file("extdata", package = "methylInheritance"), -#' pattern = "TEST", full.names = TRUE) +#' filesDir <- system.file("extdata", "TEST", package="methylInheritance") #' #' ## Load information from files #' results <- loadAllRDSResults(analysisResultsDir = filesDir, -#' permutationResultsDir = filesDir, doingSites = TRUE, doingTiles = TRUE) +#' permutationResultsDir = filesDir, doingSites = TRUE, doingTiles = TRUE) #' #' ## Extract information for the intersection between conserved differentially #' ## methylated sites (type = sites) between the intersection of 2 #' ## generations (inter = i2): F1 and F2 (position = 1) -#' info <- extractInfo(allResults = results, -#' type = "sites", inter="i2", 1) +#' info <- extractInfo(allResults = results, type = "sites", inter="i2", 1) #' #' @author Astrid Deschenes, Pascal Belleau #' @export extractInfo <- function(allResults, type=c("sites", "tiles"), - inter=c("i2", "iAll"), position) { + inter=c("i2", "iAll"), position=1) { + ## Validate type value + type <- match.arg(type) + + ## Validate type value + inter <- match.arg(inter) + + ## Validate other parameters validateExtractInfo(allResults = allResults, type, inter, position) type <- toupper(type) @@ -1526,7 +943,7 @@ extractInfo <- function(allResults, type=c("sites", "tiles"), real[["HYPER"]][[position]]), SOURCE=c("OBSERVATION", "OBSERVATION")) - for (i in 1:length(allResults[["PERMUTATION"]])) { + for (i in seq_len(length(allResults[["PERMUTATION"]]))) { permutation <- allResults[["PERMUTATION"]][[i]][[type]][[inter]] dataConserved <- rbind(dataConserved, data.frame(TYPE=c("HYPO", "HYPER"), @@ -1542,11 +959,11 @@ extractInfo <- function(allResults, type=c("sites", "tiles"), #' @title Generate a graph for a permutation analysis #' #' @description Generate a graph for a permutation analysis using observed -#' and permutated results. +#' and shuffled results. #' #' @param formatForGraphDataFrame a \code{data.frame} containing the #' observation results (using real -#' data) and the permutation results (using permutated data). Both hyper and +#' data) and the permutation results (using shuffled data). Both hyper and #' hypo differentially conserved methylation results must be present. The #' \code{data.frame} must have 3 columns : "TYPE", "RESULT" and "SOURCE". #' The "TYPE" can be either "HYPER" or "HYPO". The "RESULT" is the number @@ -1564,7 +981,7 @@ extractInfo <- function(allResults, type=c("sites", "tiles"), #' ## methylated sites (type = sites) between the intersection of 2 #' ## generations (inter = i2): F2 and F3 (position = 2) #' info <- extractInfo(allResults = methylInheritanceResults, -#' type = "sites", inter="i2", 2) +#' type = "sites", inter="i2", 2) #' #' ## Create graph #' plotGraph(info) @@ -1580,7 +997,7 @@ plotGraph <- function(formatForGraphDataFrame) { # Columns names : TYPE (HYPER or HYPO), RESULT (nbr conseved sites), # SOURCE (OBSERVED or PERMUTATION) p <- ggplot(data=formatForGraphDataFrame, - aes(x=formatForGraphDataFrame$RESULT)) + + aes(x=RESULT)) + geom_histogram(col="blue", fill="lightblue", binwidth=2, alpha = .2) + labs(title = "") + @@ -1592,30 +1009,25 @@ plotGraph <- function(formatForGraphDataFrame) { # Add vertical line corresponding to the number of conserved elements # in the observed results (real results) + + RESULT <- NULL interceptFrame <- subset(formatForGraphDataFrame, formatForGraphDataFrame$SOURCE == "OBSERVATION") p <- p + geom_vline(data = interceptFrame, - aes(xintercept = interceptFrame$RESULT, - color="observed"), linetype="longdash", - show.legend=TRUE) + aes(xintercept=RESULT, color="observed"), + linetype="longdash", show.legend=TRUE) p <- p + scale_color_manual(name = "", values = c(observed = "red")) + theme(legend.position="bottom") # Calculate the significant level for HYPER AND HYPO - hypoDataSet <- subset(formatForGraphDataFrame, - formatForGraphDataFrame$TYPE == "HYPO") - hypoTotal <- nrow(hypoDataSet) - hypoNumber <- interceptFrame[interceptFrame$TYPE == "HYPO",]$RESULT - signifLevelHypo <- nrow(subset(hypoDataSet, - hypoDataSet$RESULT >= hypoNumber))/hypoTotal - - hyperDataSet <- subset(formatForGraphDataFrame, - formatForGraphDataFrame$TYPE == "HYPER") - hyperTotal <- nrow(hyperDataSet) + signif <- calculateSignificantLevel(formatForGraphDataFrame) + + signifLevelHypo <- signif[["HYPO"]] + signifLevelHyper <- signif[["HYPER"]] + hyperNumber <- interceptFrame[interceptFrame$TYPE == "HYPER",]$RESULT - signifLevelHyper <- nrow(subset(hyperDataSet, - hyperDataSet$RESULT >= hyperNumber))/hyperTotal + hypoNumber <- interceptFrame[interceptFrame$TYPE == "HYPO",]$RESULT # Number of observed conserved elements as annotated text info <- data.frame(type = c("HYPER", "HYPO"), @@ -1629,3 +1041,177 @@ plotGraph <- function(formatForGraphDataFrame) { return(g) } + + +#' @title Load convergence information from RDS files +#' +#' @description Load convergence information from RDS files. +#' +#' @param analysisResultsDir a \code{character} string, the path to the +#' directory that contains the analysis results. The path can be the same as +#' for the \code{permutatioNResultsDir} parameter. +#' +#' @param permutationResultsDir a \code{character} string, the path to the +#' directory that contains the permutation results. The path can be the same +#' as for the \code{analysisResultsDir} parameter. +#' +#' @param type One of the \code{"sites"} or \code{"tiles"} strings. +#' Specifies the type +#' of differentially methylated elements should be returned. For +#' retrieving differentially methylated bases \code{type} = \code{"sites"}; for +#' differentially methylated regions \code{type} = \code{"tiles"}. +#' Default: \code{"sites"}. +#' +#' @param inter One of the \code{"i2"} or \code{"iAll"} strings. Specifies the +#' type of intersection should be returned. For +#' retrieving intersection results between two consecutive generations +#' \code{inter} = \code{"i2"}; for intersection results between three +#' generations or more \code{inter} = \code{"iAll"}. +#' Default: \code{"i2"}. +#' +#' @param position a positive \code{integer}, the position in the \code{list} +#' where the information will be extracted. +#' +#' @param by a \code{integer}, the increment of the number of permutations +#' where the significant level is tested. Default: 100. +#' +#' @return a graph showing the evolution of the significant level with the +#' number of permutations +#' +#' @examples +#' +#' ## Get the name of the directory where files are stored +#' filesDir <- system.file("extdata", "TEST", package="methylInheritance") +#' +#' ## Load convergence information +#' results <- loadConvergenceData(analysisResultsDir = filesDir, +#' permutationResultsDir = filesDir, type="sites", inter="i2", position=1, +#' by=1) +#' +#' @author Astrid Deschenes, Pascal Belleau +#' @export +loadConvergenceData <- function(analysisResultsDir, + permutationResultsDir, type = c("sites", "tiles"), + inter = c("i2", "iAll"), position, by = 100) { + ## Validate type value + type <- match.arg(type) + + ## Validate type value + inter <- match.arg(inter) + + ## Validate other parameters + validateLoadConvergenceData(analysisResultsDir, permutationResultsDir, + position, by) + + ## Add last slash to analysisResultsDir when absent + if (substr(analysisResultsDir, nchar(analysisResultsDir), + nchar(analysisResultsDir)) != "/") { + analysisResultsDir <- paste0(analysisResultsDir, "/") + } + + ## Add last slash to permutationResultsDir when absent + if (substr(permutationResultsDir, nchar(permutationResultsDir), + nchar(permutationResultsDir)) != "/") { + permutationResultsDir <- paste0(permutationResultsDir, "/") + } + + if (type == "sites") { + doingSites = TRUE + doingTiles = FALSE + } else { + doingSites = FALSE + doingTiles = TRUE + } + + ## Get maximum number of files and create a incrementing sequence using + ## the "by" parameter + filesInDir <- list.files(path = paste0(permutationResultsDir, toupper(type), + "/"), pattern = "[[:digit:]].RDS", all.files = FALSE, + full.names = TRUE, recursive = FALSE, + ignore.case = FALSE, include.dirs = FALSE, no.. = FALSE) + + nbFiles <- length(filesInDir) + seqFiles <- unique(c(seq(by, nbFiles, by), nbFiles)) + + ## The returned data.frame + final <- data.frame(NBR_PERMUTATIONS = integer(), ELEMENT = character(), + TYPE = character(), ANALYSIS = character(), + POSITION = integer(), + SIGNIFICANT_LEVEL = numeric(), + stringsAsFactors=FALSE) + + for (i in seqFiles) { + ## Load data associated to the selected number of files + data <- loadAllRDSResults(analysisResultsDir = analysisResultsDir, + permutationResultsDir = permutationResultsDir, + doingSites = doingSites, doingTiles = doingTiles, + maxID = i) + + ## Extract info + info <- extractInfo(allResults = data, type = type, + inter = inter, position) + + ## Calculate significant level + result <- calculateSignificantLevel(info) + + ## Create data.frame using extracted information + temp <- data.frame(NBR_PERMUTATIONS = rep(i, 2), + ELEMENT = rep(toupper(type), 2), ANALYSIS = rep(inter, 2), + POSITION = rep(position, 2), TYPE = c("HYPER", "HYPO"), + SIGNIFICANT_LEVEL = c(result$HYPER, result$HYPO), + stringsAsFactors = FALSE) + + ## Add the information to the returned data.frame + final <- rbind(final, temp) + } + + ## The final data.frame containing significant levels for all entries + ## of the incrementing sequence of number of permutations + return(final) +} + + +#' @title Generate a graph showing the convergence for a permutation analysis +#' +#' @description Generate a graph showing the convergence for a permutation +#' analysis using observed and permuted results. +#' +#' @param dataFrameConvergence a \code{data.frame} containing the +#' significant levels at different number of cycles (total number of +#' permuted data analysed). The +#' \code{data.frame} must have 6 columns : "NBR_PERMUTATIONS", "ELEMENT". +#' "ANALYSIS", "POSITION", "TYPE" and "SIGNIFICANT_LEVEL". The "ELEMENT" can +#' be either "SITES" or "TILES". The "TYPE" can be either "HYPER" or "HYPO". +#' +#' @return a \code{ggplot} object. +#' +#' @examples +#' +#' ## Get the name of the directory where files are stored +#' filesDir <- system.file("extdata", "TEST", package="methylInheritance") +#' +#' ## Extract convergenc information for F1 and F2 and F3 +#' data <- loadConvergenceData(analysisResultsDir = filesDir, +#' permutationResultsDir = filesDir, type = "sites", inter = "iAll", +#' position = 1, by = 1) +#' +#' ## Create convergence graph +#' plotConvergenceGraph(data) +#' +#' @author Astrid Deschenes, Pascal Belleau +#' @importFrom ggplot2 ggplot geom_point geom_line facet_grid aes xlab ylab +#' @export +plotConvergenceGraph <- function(dataFrameConvergence) { + + ## Create graph + NBR_PERMUTATIONS <- NULL + SIGNIFICANT_LEVEL <- NULL + graph <- ggplot(data=dataFrameConvergence, aes(x=NBR_PERMUTATIONS, + y=SIGNIFICANT_LEVEL)) + geom_point(color = 'blue', size=2) + + geom_line(color='blue', linetype = "dashed", linewidth=1) + + facet_grid(TYPE ~ .) + ylab("Significant Level") + + xlab("Number of permutations") + + ## Return graph + return(graph) +} diff --git a/R/print.methylInheritanceAllResults.R b/R/print.methylInheritanceAllResults.R index 90063cc..8d6d4d8 100644 --- a/R/print.methylInheritanceAllResults.R +++ b/R/print.methylInheritanceAllResults.R @@ -31,7 +31,7 @@ print.methylInheritanceAllResults <- function(x, ...) { nbGenerations <- 0 if (!is.null(x$OBSERVATION$SITES)) { nbGenerations = length(x$OBSERVATION$SITES$i2) + 1 - } else if (!is.null(x$OBSERVATION$SITES)) { + } else if (!is.null(x$OBSERVATION$TILES)) { nbGenerations = length(x$OBSERVATION$TILES$i2) + 1 } @@ -42,6 +42,8 @@ print.methylInheritanceAllResults <- function(x, ...) { isSites <- FALSE + result <- NULL + ## Extract info about sites when present if (!is.null(x$OBSERVATION$SITES)) { tt <- unlist(x$OBSERVATION$SITES) @@ -81,6 +83,10 @@ print.methylInheritanceAllResults <- function(x, ...) { cat("Number of Generations: ", nbGenerations, "\n") cat("Number of Permutations: ", nbPermutations , "\n\n") cat("Observation Results: \n") - print.data.frame(result) + if (!is.null(result)) { + print.data.frame(result) + } else { + cat("\tNo observation result.") + } invisible(x) } diff --git a/README.md b/README.md index 7c8834d..22c6874 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [![Build Status](https://travis-ci.org/adeschen/methylInheritance.svg?branch=master)](https://travis-ci.org/adeschen/methylInheritance) [![codecov](https://codecov.io/gh/adeschen/methylInheritance/branch/master/graph/badge.svg)](https://codecov.io/gh/adeschen/methylInheritance) - +[![License: Artistic-2.0](https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg)](https://opensource.org/licenses/Artistic-2.0) ## Conserved Differentially Methylated Elements from One Generation to the Next: Inheritance versus Randomness @@ -12,14 +12,27 @@ elements, between several generations, is associated to an effect inherited from a treatment and that stochastic effect can be dismissed. + ## Citing ## If you use this package for a publication, we would ask you to cite the following: -> Astrid Deschênes, Pascal Belleau and Arnaud Droit (2016). methylInheritance: Permutation-Based Analysis associating Conserved Differentially Methylated Elements from One Generation to the Next to a Treatment Effect. R package version 0.99.0. +> Pascal Belleau, Astrid Deschênes, Marie-Pier Scott-Boyer, Romain Lambrot, Mathieu Dalvai, Sarah Kimmins, Janice Bailey, Arnaud Droit; Inferring and modeling inheritance of differentially methylated changes across multiple generations, Nucleic Acids Research, Volume 46, Issue 14, 21 August 2018, Pages e85. DOI: https://doi.org/10.1093/nar/gky362 + + +## Bioconductor Package ## + +[![Bioconductor Time](http://bioconductor.org/shields/years-in-bioc/methylInheritance.svg)](http://bioconductor.org/packages/release/bioc/html/methylInheritance.html "Bioconductor status") -> Akalin A, Kormaksson M, Li S, Garrett-Bakelman FE, Figueroa ME, Melnick A and Mason CE (2012). “methylKit: a comprehensive R package for the analysis of genome-wide DNA methylation profiles.” Genome Biology, 13(10), pp. R87. +methylInheritance is now an official package of [Bioconductor](http://bioconductor.org/). The current release can be directly downloaded from their website: +[Current release](http://bioconductor.org/packages/methylInheritance) + + +## Description of Package Functionality ## + +The vignette of the methylInheritance package, which is a document that provides a task-oriented description of the package functionality, is available on Bioconductor website: +[methylInheritance vignette](https://bioconductor.org/packages/release/bioc/vignettes/methylInheritance/inst/doc/methylInheritance.html) ## Authors ## @@ -28,9 +41,6 @@ following: [Pascal Belleau](http://ca.linkedin.com/in/pascalbelleau "Pascal Belleau") and [Arnaud Droit](http://ca.linkedin.com/in/drarnaud "Arnaud Droit"). -See [Arnaud Droit Lab](http://bioinformatique.ulaval.ca "Arnaud Droit Lab") -website. - ## License ## diff --git a/inst/CITATION b/inst/CITATION new file mode 100644 index 0000000..f9d1e48 --- /dev/null +++ b/inst/CITATION @@ -0,0 +1,20 @@ +citEntry(entry="article", + title = "Inferring and modeling inheritance of differentially methylated changes across multiple generations", + author = personList( as.person("Pascal Belleau" ), + as.person("Astrid Desch{\\^{e}}nes" ), + as.person("Marie-Pier Scott-Boyer" ), + as.person("Romain Lambrot"), + as.person("Mathieu Dalvai" ), + as.person("Sarah Kimmins"), + as.person("Janice Bailey" ), + as.person("Arnaud Droit" )), + year = 2018, + journal = "Nucleic Acids Research", + volume = "46", + issue = "14", + pages = "e85", + doi = "10.1093/nar/gky362", + url = "https://doi.org/10.1093/nar/gky362", + textVersion = + "Belleau P, Deschênes A, Scott-Boyer M-P, Lambrot R, Dalvai, M, Kimmins S, Bailey J et Droit A. Inferring and modeling inheritance of differentially methylated changes across multiple generations. Nucleic Acids Research. Volume 46, Issue 14, 21 August 2018, Pages e85. DOI: https://doi.org/10.1093/nar/gky362" +) diff --git a/inst/NEWS b/inst/NEWS index e69de29..95daace 100644 --- a/inst/NEWS +++ b/inst/NEWS @@ -0,0 +1,37 @@ +CHANGES IN VERSION 1.33.1 +------------------------ + +BUG FIXES AND IMPROVEMENTS + + o Ensure functions using ggplot2 are using update functions + + +CHANGES IN VERSION 1.15.1 +------------------------ + +BUG FIXES AND IMPROVEMENTS + + o Fix bug causing problem when using loadConvergenceData() with a different directory for the observation file and the permutation files. + + +CHANGES IN VERSION 1.5.1 +------------------------ + +SIGNIFICANT USER-VISIBLE CHANGES + + o New citation referring to the associated published article in Nucleic Acids Research. + + +CHANGES IN VERSION 1.1.1 +------------------------ + +SIGNIFICANT USER-VISIBLE CHANGES + + o Functions runObservation() and runPermutation() don't return the result anymore. The results are saved in RDS files. The results can be loaded through the loadAllRDSResults() function. + o New plotConvergence() function enable visualization of convergence + o New "saveInfoByGeneration" parameter which generates RDS files containing information about each generation for each permutation + + +BUG FIXES AND IMPROVEMENTS + + o Major changes in parallel processing to limit memory consumption diff --git a/inst/extdata/TEST/SITES/SITES_observed_results.RDS b/inst/extdata/TEST/SITES/SITES_observed_results.RDS index 417a3ff..219e988 100644 Binary files a/inst/extdata/TEST/SITES/SITES_observed_results.RDS and b/inst/extdata/TEST/SITES/SITES_observed_results.RDS differ diff --git a/inst/extdata/TEST/SITES/SITES_permutation_1.RDS b/inst/extdata/TEST/SITES/SITES_permutation_1.RDS index ffb5f2c..dce1663 100644 Binary files a/inst/extdata/TEST/SITES/SITES_permutation_1.RDS and b/inst/extdata/TEST/SITES/SITES_permutation_1.RDS differ diff --git a/inst/extdata/TEST/SITES/SITES_permutation_2.RDS b/inst/extdata/TEST/SITES/SITES_permutation_2.RDS index c3e91c5..50f2f0e 100644 Binary files a/inst/extdata/TEST/SITES/SITES_permutation_2.RDS and b/inst/extdata/TEST/SITES/SITES_permutation_2.RDS differ diff --git a/inst/extdata/TEST/SITES/SITES_permutation_3.RDS b/inst/extdata/TEST/SITES/SITES_permutation_3.RDS index 37b2e92..672cb61 100644 Binary files a/inst/extdata/TEST/SITES/SITES_permutation_3.RDS and b/inst/extdata/TEST/SITES/SITES_permutation_3.RDS differ diff --git a/inst/extdata/TEST/TILES/TILES_observed_results.RDS b/inst/extdata/TEST/TILES/TILES_observed_results.RDS index 340a005..a9c36ea 100644 Binary files a/inst/extdata/TEST/TILES/TILES_observed_results.RDS and b/inst/extdata/TEST/TILES/TILES_observed_results.RDS differ diff --git a/inst/extdata/TEST/TILES/TILES_permutation_1.RDS b/inst/extdata/TEST/TILES/TILES_permutation_1.RDS index e050f1c..bdf4d70 100644 Binary files a/inst/extdata/TEST/TILES/TILES_permutation_1.RDS and b/inst/extdata/TEST/TILES/TILES_permutation_1.RDS differ diff --git a/inst/extdata/TEST/TILES/TILES_permutation_2.RDS b/inst/extdata/TEST/TILES/TILES_permutation_2.RDS index 6a553a6..5b50d05 100644 Binary files a/inst/extdata/TEST/TILES/TILES_permutation_2.RDS and b/inst/extdata/TEST/TILES/TILES_permutation_2.RDS differ diff --git a/inst/extdata/TEST/TILES/TILES_permutation_3.RDS b/inst/extdata/TEST/TILES/TILES_permutation_3.RDS index 50be8f6..4506641 100644 Binary files a/inst/extdata/TEST/TILES/TILES_permutation_3.RDS and b/inst/extdata/TEST/TILES/TILES_permutation_3.RDS differ diff --git a/inst/extdata/TEST_01/observations/SITES/SITES_observed_results.RDS b/inst/extdata/TEST_01/observations/SITES/SITES_observed_results.RDS new file mode 100644 index 0000000..e41d447 Binary files /dev/null and b/inst/extdata/TEST_01/observations/SITES/SITES_observed_results.RDS differ diff --git a/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_1.RDS b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_1.RDS new file mode 100644 index 0000000..0c984f9 Binary files /dev/null and b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_1.RDS differ diff --git a/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_10.RDS b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_10.RDS new file mode 100644 index 0000000..3bacb75 Binary files /dev/null and b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_10.RDS differ diff --git a/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_2.RDS b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_2.RDS new file mode 100644 index 0000000..ee87fab Binary files /dev/null and b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_2.RDS differ diff --git a/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_3.RDS b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_3.RDS new file mode 100644 index 0000000..3bbf86e Binary files /dev/null and b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_3.RDS differ diff --git a/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_4.RDS b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_4.RDS new file mode 100644 index 0000000..8abaabe Binary files /dev/null and b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_4.RDS differ diff --git a/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_5.RDS b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_5.RDS new file mode 100644 index 0000000..da12add Binary files /dev/null and b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_5.RDS differ diff --git a/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_6.RDS b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_6.RDS new file mode 100644 index 0000000..94f94ca Binary files /dev/null and b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_6.RDS differ diff --git a/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_7.RDS b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_7.RDS new file mode 100644 index 0000000..3079ab7 Binary files /dev/null and b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_7.RDS differ diff --git a/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_8.RDS b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_8.RDS new file mode 100644 index 0000000..d9545cc Binary files /dev/null and b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_8.RDS differ diff --git a/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_9.RDS b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_9.RDS new file mode 100644 index 0000000..68a223d Binary files /dev/null and b/inst/extdata/TEST_01/permutations/SITES/SITES_permutation_9.RDS differ diff --git a/inst/unitTests/test_methylInheritanceInternalMethods.R b/inst/unitTests/test_methylInheritanceInternalMethods.R index 369a32a..b6a6a8c 100644 --- a/inst/unitTests/test_methylInheritanceInternalMethods.R +++ b/inst/unitTests/test_methylInheritanceInternalMethods.R @@ -7,13 +7,23 @@ ## Test the methylInheritanceInternalMethods functions ################################################### -DIRECTORY <- system.file("extdata", package = "methylInheritance") -METHYL_OBJ_FILE <- dir(system.file("extdata", package = "methylInheritance"), - pattern = "methylObj_001.RDS", full.names = TRUE) +library("GenomicRanges") + +METHYL_OBJ_FILE <- system.file("extdata", "methylObj_001.RDS", + package = "methylInheritance") METHYL_OBJ <- readRDS(METHYL_OBJ_FILE) +data(methylInheritanceResults) + +.tearDown <- function() { + if (dir.exists("test_001")) { + unlink("test_001", recursive = TRUE, force = TRUE) + } +} + + ########################################################### ## runOnePermutationOnAllGenerations() function ########################################################### @@ -22,7 +32,8 @@ METHYL_OBJ <- readRDS(METHYL_OBJ_FILE) test.validateRunPermutationUsingMethylKitInfo_sites_good_01 <- function() { ## Extract information set.seed(111) - allSamples <- sample(unlist(METHYL_OBJ, recursive = FALSE), 36, replace = F) + allSamples <- sample(unlist(METHYL_OBJ, recursive = FALSE), 36, + replace = FALSE) treatment <- c(0,0,0,0,0,0,1,1,1,1,1,1) sampleList01 <- new("methylRawList", allSamples[1:12], treatment = treatment) @@ -30,65 +41,574 @@ test.validateRunPermutationUsingMethylKitInfo_sites_good_01 <- function() { treatment = treatment) sampleList03 <- new("methylRawList", allSamples[25:36], treatment = treatment) - input <- list(sample = list(sampleList01, sampleList02, sampleList03), - id = 1) + input <- list(sampleList01, sampleList02, sampleList03) + + if (!dir.exists("test_001")) { + dir.create("test_001/SITES/", recursive = TRUE) + } - obs <- tryCatch(methylInheritance:::runOnePermutationOnAllGenerations( - methylInfoForAllGenerations = input, outputDir = NULL, type = "sites", + obs <- methylInheritance:::runOnePermutationOnAllGenerations( + id = 1, methylInfoForAllGenerations = input, outputDir = "test_001/", type = "sites", nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = FALSE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100), - error=conditionMessage) + tileSize = 1000, stepSize = 100, restartCalculation = FALSE, saveInfoByGeneration = FALSE) exp <- list() exp[["SITES"]] <- list() exp[["SITES"]][["i2"]] <- list() - exp[["SITES"]][["i2"]][["HYPER"]] <- list(0,5) - exp[["SITES"]][["i2"]][["HYPO"]] <- list(0,1) + exp[["SITES"]][["i2"]][["HYPER"]] <- list(0,0) + exp[["SITES"]][["i2"]][["HYPO"]] <- list(3,0) exp[["SITES"]][["iAll"]][["HYPER"]] <- list(0) exp[["SITES"]][["iAll"]][["HYPO"]] <- list(0) + obsV <- methylInheritance::loadAllRDSResults(permutationResultsDir = "test_001", analysisResultsDir = NULL) + message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_sites_good_01() ", - "- Valid paramters did not generated expected results.") + "- Valid parameters did not generated expected results.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, 0, msg = message) + checkEquals(obsV$PERMUTATION[[1]], exp, msg = message) } -## Test tiles when all parameters are valid -test.validateRunPermutationUsingMethylKitInfo_tiles_good_01 <- function() { - ## Extract information - set.seed(11) - allSamples <- sample(unlist(METHYL_OBJ, recursive = FALSE), 36, - replace = F) - treatment <- c(0,0,0,0,0,0,1,1,1,1,1,1) - sampleList01 <- new("methylRawList", allSamples[1:12], - treatment = treatment) - sampleList02 <- new("methylRawList", allSamples[13:24], - treatment = treatment) - sampleList03 <- new("methylRawList", allSamples[25:36], - treatment = treatment) - input <- list(sample = list(sampleList01, sampleList02, sampleList03), - id = 1) +########################################################### +## isInterGenerationResults() function +########################################################### - obs <- tryCatch(methylInheritance:::runOnePermutationOnAllGenerations( - methylInfoForAllGenerations = input, outputDir = NULL, type = "tiles", - nbrCoresDiffMeth = 1, - minReads = 5, minMethDiff = 5, qvalue = 0.05, - maxPercReads = 99.9, destrand = FALSE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100), +test.isInterGenerationResults_true <- function() { + + filesDir <- system.file("extdata", "TEST", package="methylInheritance") + + obs <- methylInheritance:::isInterGenerationResults(outputDir = + paste0(filesDir, "/"), 0, "sites") + + message <- paste0("test.isInterGenerationResults_true() ", + "- Function should return TRUE") + + checkTrue(obs, msg = message) +} + + +########################################################### +## validateExtractInfo() function +########################################################### + +test.validateExtractInfo_position_zero <- function() { + + obs <- tryCatch(methylInheritance:::validateExtractInfo( + allResults = methylInheritanceResults, type = "sites", + inter = "i2", position = 0), error=conditionMessage) - exp <- list() - exp[["TILES"]] <- list() - exp[["TILES"]][["i2"]] <- list() - exp[["TILES"]][["i2"]][["HYPER"]] <- list(1300, 0) - exp[["TILES"]][["i2"]][["HYPO"]] <- list(0, 0) - exp[["TILES"]][["iAll"]][["HYPER"]] <- list(0) - exp[["TILES"]][["iAll"]][["HYPO"]] <- list(0) + exp <- "position must be a positive integer" + + message <- paste0("test.validateExtractInfo_position_zero() - ", + "Zero position value did not generated expected message.") + + checkEquals(obs, exp, message) +} + +test.validateExtractInfo_position_string <- function() { + + obs <- tryCatch(methylInheritance:::validateExtractInfo( + allResults = methylInheritanceResults, type = "sites", + inter = "i2", position = "hi"), + error=conditionMessage) + + exp <- "position must be a positive integer" + + message <- paste0("test.validateExtractInfo_position_string() - ", + "Zero position value did not generated expected message.") + + checkEquals(obs, exp, message) +} + +test.validateExtractInfo_allResults_vector <- function() { + + obs <- tryCatch(methylInheritance:::validateExtractInfo( + allResults = c(1,2,3), type = "sites", + inter = "i2", position = 1), + error=conditionMessage) + + exp <- "allResults must be of class \"methylInheritanceAllResults\"" + + message <- paste0("test.validateExtractInfo_allResults_vector() - ", + "allResults vector did not generated expected message.") + + checkEquals(obs, exp, message) +} + +test.validateExtractInfo_type_wrong <- function() { + + obs <- tryCatch(methylInheritance:::validateExtractInfo( + allResults = methylInheritanceResults, type = "toto", + inter = "i2", position = 1), + error=conditionMessage) - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_tiles_good_01() ", - "- Valid paramters did not generated expected results.") + exp <- "allResults must have an element called \"TOTO\" in its \"OBSERVATION\" list" + + message <- paste0("test.validateExtractInfo_type_wrong() - ", + "Wrong type did not generated expected message.") + + checkEquals(obs, exp, message) +} + +test.validateExtractInfo_type_wrong <- function() { + + obs <- tryCatch(methylInheritance:::validateExtractInfo( + allResults = methylInheritanceResults, type = "sites", + inter = "hi", position = 1), + error=conditionMessage) + + exp <- "allResults must have an element called \"hi\" in the \"SITES\" list present in its \"OBSERVATION\" list" + + message <- paste0("test.validateExtractInfo_type_wrong() - ", + "Wrong inter did not generated expected message.") + + checkEquals(obs, exp, message) +} + +test.validateExtractInfo_position_too_high <- function() { + + obs <- tryCatch(methylInheritance:::validateExtractInfo( + allResults = methylInheritanceResults, type = "sites", + inter = "i2", position = 4), + error=conditionMessage) + + exp <- "position must correspond to a valid entry in the \"allResults$OBSERVATION[[SITES]][[i2]]\"" + + message <- paste0("test.validateExtractInfo_position_too_high() - ", + "Too high position value did not generated expected message.") + + checkEquals(obs, exp, message) +} + +test.validateExtractInfo_allResults_no_permutation <- function() { + g<-list() + g[["OBSERVATION"]] <- methylInheritanceResults$OBSERVATION + class(g)<-"methylInheritanceAllResults" + + obs <- tryCatch(methylInheritance:::validateExtractInfo( + allResults = g, type = "sites", + inter = "i2", position = 1), + error=conditionMessage) + + exp <- "allResults must have an element called \"PERMUTATION\"" + + message <- paste0("test.validateExtractInfo_allResults_no_permutation() - ", + "allResult without permutation value did not generated expected message.") + + checkEquals(obs, exp, message) +} + +test.validateExtractInfo_allResults_no_observation <- function() { + g<-list() + g[["PERMUTATION"]] <- methylInheritanceResults$OBSERVATION + class(g)<-"methylInheritanceAllResults" + + obs <- tryCatch(methylInheritance:::validateExtractInfo( + allResults = g, type = "sites", + inter = "i2", position = 1), + error=conditionMessage) + + exp <- "allResults must have an element called \"OBSERVATION\"" + + message <- paste0("test.validateExtractInfo_allResults_no_observation() - ", + "allResult without observation value did not generated expected message.") + + checkEquals(obs, exp, message) +} + +test.validateExtractInfo_allResults_not_list <- function() { + g<-vector() + class(g)<-"methylInheritanceAllResults" + + obs <- tryCatch(methylInheritance:::validateExtractInfo( + allResults = g, type = "sites", + inter = "i2", position = 1), + error=conditionMessage) + + exp <- "allResults must be a list" + + message <- paste0("test.validateExtractInfo_allResults_not_list() - ", + "allResult not list did not generated expected message.") + + checkEquals(obs, exp, message) +} + +########################################################### +## validateLoadConvergenceData() function +########################################################### + +test.validateLoadConvergenceData_integer_analysisDir <- function() { + + obs <- tryCatch(methylInheritance:::validateLoadConvergenceData(analysisResultsDir = 33, + permutationResultsDir = "./", position = 1, by = 2), + error=conditionMessage) + + exp <- "analysisResultsDir must be a character string" + + message <- paste0("test.validateLoadConvergenceData_integer_analysisDir() - ", + "Integer as analysis directory did not generated expected message.") + + checkEquals(obs, exp, message) +} + +test.validateLoadConvergenceData_integer_permutationDir <- function() { + obs <- tryCatch(methylInheritance:::validateLoadConvergenceData(analysisResultsDir = "./", + permutationResultsDir = 44, position = 1, by = 2), + error=conditionMessage) + + exp <- "permutationResultsDir must be a character string" + + message <- paste0("test.validateLoadConvergenceData_integer_permutationDir() - ", + "Integer as permutation directory did not generated expected message.") + + checkEquals(obs, exp, message) +} + +test.validateLoadConvergenceData_position_zero <- function() { + obs <- tryCatch(methylInheritance:::validateLoadConvergenceData(analysisResultsDir = "./", + permutationResultsDir = "./", position = 0, by = 2), + error=conditionMessage) + + exp <- "position must be a positive integer" + + message <- paste0("test.validateLoadConvergenceData_position_zero() - ", + "Zero as position did not generated expected message.") + + checkEquals(obs, exp, message) +} + +test.validateLoadConvergenceData_by_zero <- function() { + obs <- tryCatch(methylInheritance:::validateLoadConvergenceData(analysisResultsDir = "./", + permutationResultsDir = "./", position = 1, by = 0), + error=conditionMessage) + + exp <- "by must be a positive integer" + + message <- paste0("test.validateLoadConvergenceData_by_zero() - ", + "Zero as by did not generated expected message.") + + checkEquals(obs, exp, message) +} + +########################################################### +## calculateSignificantLevel() function +########################################################### + +test.calculateSignificantLevel_true <- function() { + + filesDir <- system.file("extdata", "TEST", package="methylInheritance") + + results <- loadAllRDSResults(analysisResultsDir = filesDir, + permutationResultsDir = filesDir, doingSites = TRUE, + doingTiles = FALSE) + + iAll <- extractInfo(results, type = "sites", inter = "iAll", 1) + + obs <- methylInheritance:::calculateSignificantLevel(iAll) + + message <- paste0("test.calculateSignificantLevel_true() ", + "- Function did not return expected values") + + exp <- list(HYPER=1.0, HYPO=(2.0/4.0)) checkEquals(obs, exp, msg = message) } + +########################################################### +## readInterGenerationResults() function +########################################################### + +test.readInterGenerationResults_good_01 <- function() { + + filesDir <- system.file("extdata", "TEST", package="methylInheritance") + + ## Read DMS intergenerational results for the observed data + obs <- methylInheritance:::readInterGenerationResults(outputDir = + paste0(filesDir, "/"), 0, "sites") + + message <- paste0("test.readInterGenerationResults_good_01() ", + "- Function did not return expected values") + + iAll_1 <- GenomicRanges::GRanges(seqnames = rep("S", 4), + ranges = IRanges::IRanges(start = c(30222185, 15048832, 22963194, 23499048), + end = c(30222185, 15048832, 22963194, 23499048)), + strand = rep("+", 4), + typeDiff = c(1, rep(-1, 3))) + + i2_2 <- GenomicRanges::GRanges(seqnames = rep("S", 22), + ranges = IRanges::IRanges(start = c(97481, 572272, 3281006, 11121503, 19260516, + 19445653, 22874019, 27232572, 30222185, 35929511, + 6085769, 8045209, 10355001, 11147625, 15048832, + 15438496, 22745004, 22899924, 22963194, 23499048, + 28622167, 34611139), + end = c(97481, 572272, 3281006, 11121503, 19260516, + 19445653, 22874019, 27232572, 30222185, 35929511, + 6085769, 8045209, 10355001, 11147625, 15048832, + 15438496, 22745004, 22899924, 22963194, 23499048, + 28622167, 34611139)), + strand = rep("+", 22), + typeDiff = c(rep(1, 10), rep(-1, 12))) + + i2_1 <- GenomicRanges::GRanges(seqnames = rep("S", 36), + ranges = IRanges::IRanges(start = c(570115, 2573229, 5063112, 8247138, 8765627, 8791494, + 9955639, 11667875, 19095767, 26225126, 26798489, 27089337, + 27188724, 27236909, 27421271, 30222185, 30786437, 31364173, + 31396094, 33611091, 33886929, 3139258, 14391040, 15048832, + 15438613, 16630377, 17795264, 18396852, 22963194, 23499048, + 23499106, 23499111, 27019812, 30204193, 30746773, 35827911), + end = c(570115, 2573229, 5063112, 8247138, 8765627, 8791494, + 9955639, 11667875, 19095767, 26225126, 26798489, 27089337, + 27188724, 27236909, 27421271, 30222185, 30786437, 31364173, + 31396094, 33611091, 33886929, 3139258, 14391040, 15048832, + 15438613, 16630377, 17795264, 18396852, 22963194, 23499048, + 23499106, 23499111, 27019812, 30204193, 30746773, 35827911)), + strand = rep("+", 36), + typeDiff = c(rep(1, 21), rep(-1, 15))) + + exp <- list("i2" = list(i2_1, i2_2), "iAll" = list(iAll_1)) + + checkEquals(as.data.frame(i2_1), as.data.frame(exp$i2[[1]]), msg = message) + checkEquals(as.data.frame(i2_2), as.data.frame(exp$i2[[2]]), msg = message) + checkEquals(as.data.frame(iAll_1), as.data.frame(exp$iAll[[1]]), msg = message) +} + +test.readInterGenerationResults_good_02 <- function() { + + filesDir <- system.file("extdata", "TEST", package="methylInheritance") + + ## Read DMS intergenerational results for the observed data + obs <- methylInheritance:::readInterGenerationResults(outputDir = + paste0(filesDir, "/"), 1, "sites") + + message <- paste0("test.readInterGenerationResults_good_02() ", + "- Function did not return expected values") + + iAll_1 <- GenomicRanges::GRanges(seqnames = rep("S", 5), + ranges = IRanges::IRanges(start = c(17191066, 17424070, 1130005, 22786110, 26615081), + end = c(17191066, 17424070, 1130005, 22786110, 26615081)), + strand = rep("+", 5), + typeDiff = c(1, 1, rep(-1, 3))) + + i2_2 <- GenomicRanges::GRanges(seqnames = rep("S", 18), + ranges = IRanges::IRanges(start = c(5507460, 8045221, 17191066, 17424070, 32510128, + 32911751, 33071323, 1130005, 5826332, 8045207, + 17804285, 18396726, 19869520, 21672484, 22786110, + 26615081, 32216298, 32216478), + end = c(5507460, 8045221, 17191066, 17424070, 32510128, + 32911751, 33071323, 1130005, 5826332, 8045207, + 17804285, 18396726, 19869520, 21672484, 22786110, + 26615081, 32216298, 32216478)), + strand = rep("+", 18), + typeDiff = c(rep(1, 7), rep(-1, 11))) + + i2_1 <- GenomicRanges::GRanges(seqnames = rep("S", 15), + ranges = IRanges::IRanges(start = c(3401344, 17191066, 17424070, 24135743, + 27019812, 1130005, 1345775, 2573229, + 6717075, 18926407, 19260516, 22786110, + 23655774, 26615081, 33278578), + end = c(3401344, 17191066, 17424070, 24135743, + 27019812, 1130005, 1345775, 2573229, + 6717075, 18926407, 19260516, 22786110, + 23655774, 26615081, 33278578)), + strand = rep("+", 15), + typeDiff = c(rep(1, 5), rep(-1, 10))) + + exp <- list("i2" = list(i2_1, i2_2), "iAll" = list(iAll_1)) + + checkEquals(as.data.frame(i2_1), as.data.frame(exp$i2[[1]]), msg = message) + checkEquals(as.data.frame(i2_2), as.data.frame(exp$i2[[2]]), msg = message) + checkEquals(as.data.frame(iAll_1), as.data.frame(exp$iAll[[1]]), msg = message) +} + + +########################################################### +## formatInputMethylData() function +########################################################### + +test.formatInputMethylData_good_01 <- function() { + + initGR_01 <- list() + initGR_01[[1]] <- new("methylRaw", data.frame(chr = rep("S", 3), + start = c(1005, 1011, 1017), end = c(1005, 1011, 1017), + strand = strand(rep("+", 3)), coverage = c(71, 90, 95), + numCs = c(0, 1, 1), numTs = c(71, 89, 94)), sample.id = "F1_1_C", + assembly = "RNOR_5.0", context = "Cpg", resolution = 'base') + initGR_01[[2]] <- new("methylRaw", data.frame(chr = rep("S", 3), + start = c(1006, 1011, 1017), end = c(1006, 1011, 1017), + strand = strand(rep("+", 3)), coverage = c(93, 92, 93), + numCs = c(1, 4, 0), numTs = c(92, 88, 93)), sample.id = "F1_2_C", + assembly = "RNOR_5.0", context = "Cpg", resolution = 'base') + + initGR_02 <- list() + initGR_02[[1]] <- new("methylRaw", data.frame(chr = rep("S", 3), + start = c(1007, 1011, 1017), end = c(1007, 1011, 1017), + strand = strand(rep("+", 3)), coverage = c(90, 85, 79), + numCs = c(0, 0, 1), numTs = c(90, 85, 78)), sample.id = "F2_1_C", + assembly = "RNOR_5.0", context = "Cpg", resolution = 'base') + initGR_02[[2]] <- new("methylRaw", data.frame(chr = rep("S", 3), + start = c(1008, 1011, 1017), end = c(1008, 1011, 1017), + strand = strand(rep("+", 3)), coverage = c(73, 93, 78), + numCs = c(0, 2, 0), numTs = c(73, 91, 78)), sample.id = "F2_2_C", + assembly = "RNOR_5.0", context = "Cpg", resolution = 'base') + + initGR_03 <- list() + initGR_03[[1]] <- new("methylRaw", data.frame(chr = rep("S", 3), + start = c(1009, 1011, 1017), end = c(1009, 1011, 1017), + strand = strand(rep("+", 3)), coverage = c(80, 73, 84), + numCs = c(0, 0, 1), numTs = c(80, 73, 83)), sample.id = "F3_1_C", + assembly = "RNOR_5.0", context = "Cpg", resolution = 'base') + initGR_03[[2]] <- new("methylRaw", data.frame(chr = rep("S", 3), + start = c(1010, 1011, 1017), end = c(1010, 1011, 1017), + strand = strand(rep("+", 3)), coverage = c(77, 80, 94), + numCs = c(0, 2, 2), numTs = c(77, 78, 92)), sample.id = "F3_2_C", + assembly = "RNOR_5.0", context = "Cpg", resolution = 'base') + + initGR <- list() + initGR[[1]] <- new("methylRawList", initGR_01, treatment = c(0, 1)) + initGR[[2]] <- new("methylRawList", initGR_02, treatment = c(0, 1)) + initGR[[3]] <- new("methylRawList", initGR_03, treatment = c(0, 1)) + + set.seed(20011) + obs <- methylInheritance:::formatInputMethylData(initGR) + + expGR <- list() + expGR[[1]] <- new("methylRawList", list(initGR_01[[1]], initGR_02[[2]]), treatment = c(0, 1)) + expGR[[2]] <- new("methylRawList", list(initGR_02[[1]], initGR_03[[2]]), treatment = c(0, 1)) + expGR[[3]] <- new("methylRawList", list(initGR_03[[1]], initGR_01[[2]]), treatment = c(0, 1)) + + message <- paste0("test.formatInputMethylData_good_01() ", + "- Function did not return expected values") + + checkEquals(obs, expGR, message) +} + + +########################################################### +## getGRangesFromMethylDiff() function +########################################################### + +test.getGRangesFromMethylDiff_good_01 <- function() { + permutationResultsFile <- system.file("extdata", + "permutationResultsForSites.RDS", package="methylInheritance") + permutationResults <- readRDS(permutationResultsFile) + + obs <- methylInheritance:::getGRangesFromMethylDiff(methDiff = + permutationResults, pDiff = 25, qvalue = 0.01, type = "hypo") + + exp <- list() + + exp[[1]] <- GRanges(seqnames = rep("S", 6), ranges = IRanges(start = c(572272, 6716939, 19483992, + 20354283, 23499048, 27019812), + end = c(572272, 6716939, 19483992, + 20354283, 23499048, 27019812)), + strand = rep("+", 6), pvalue = c(1.700864635138675e-87, 2.441717480904409e-19, 1.137547548463320e-23, + 3.990798096127081e-17, 4.624679250110592e-99, 6.715374380810998e-18), + qvalue = c(7.472078736898228e-84, 2.167014921949277e-17, 2.039741644645623e-21, 2.897851124421653e-15, + 4.063341288403986e-95, 5.000229134166011e-16), meth.diff = c(-48.728813559322035, -27.774983021857786, -30.785123966942145, + -26.135536439702882, -65.164453701293070, -27.095834649261331)) + exp[[2]] <- GRanges(seqnames = rep("S", 3), ranges = IRanges(start = c(6062088, 15438613, 23499048), + end = c(6062088, 15438613, 23499048)), strand = rep("+", 3), pvalue = c(5.837011155738509e-61,1.461524438688262e-24, 1.704531588950500e-16), + qvalue = c(5.158856586917255e-57, 2.583443744168598e-21, 1.004330673198592e-13), meth.diff = c(-51.405910822430378,-26.548592462963523,-26.087583898151358)) + exp[[3]] <- GRanges(seqnames = rep("S", 9), ranges = IRanges(start = c(97473, 461573, 4835309, 5063112, 8045209, 15438496, 20354375, 23499048, 26267942), + end = c(97473, 461573, 4835309, 5063112, 8045209, 15438496, 20354375, 23499048, 26267942)), strand = rep("+", 9), + pvalue = c(2.070118737044828e-15, 4.845855842583129e-29, 1.181308273263934e-25, 1.176727417787188e-26, + 1.986425155223842e-16, 2.450256665272661e-22, 7.280660237109421e-24, 8.552173905506492e-20, 2.955455569819033e-18), + qvalue = c(6.777240956277343e-13, 8.654209054465339e-26, 1.506926608558130e-22, 1.751263589010490e-23, 7.095109356448416e-14, + 1.562825322679899e-19, 6.721662253713180e-21, 4.019294405074884e-17, 1.319536279207790e-15), + meth.diff = c(-25.590676883780329, -25.456545654565453, -32.198928401110869, -29.107876406501159, + -25.914367976223641, -27.358002274000036, -25.744386969983502, -27.730954849876422, -26.962446694888165)) + + message <- paste0("test.getGRangesFromMethylDiff_good_01() ", + "- Function did not return expected values") + + checkEquals(obs, exp) +} + + +########################################################### +## interGeneration() function +########################################################### + +test.interGeneration_good_01 <- function() { + + permutationResultsFile <- system.file("extdata", "permutationResultsForSites.RDS", package="methylInheritance") + permutationResults <- readRDS(permutationResultsFile) + + resultsGR <- methylInheritance:::getGRangesFromMethylDiff(methDiff = permutationResults, pDiff = 10, + qvalue = 0.01, type = "hypo") + + obs <- methylInheritance:::interGeneration(resultsGR) + + exp <- list() + exp[["i2"]] <- list() + exp[["iAll"]] <- list() + + exp[["i2"]][[1]] <- GRanges(seqnames = rep("S", 15), ranges = IRanges(start = c(3139258, 14391040, 15048832, 15438613, 16630377, + 17795264, 18396852, 22963194, 23499048, 23499106, + 23499111, 27019812, 30204193, 30746773, 35827911), + end = c(3139258, 14391040, 15048832, 15438613, 16630377, + 17795264, 18396852, 22963194, 23499048, 23499106, + 23499111, 27019812, 30204193, 30746773, 35827911)), + strand = rep("+", 15), typeDiff = rep(-1, 15)) + + exp[["i2"]][[2]] <- GRanges(seqnames = rep("S", 12), ranges = IRanges(start = c(6085769, 8045209, 10355001, 11147625, + 15048832, 15438496, 22745004, 22899924, + 22963194, 23499048, 28622167, 34611139), + end = c(6085769, 8045209, 10355001, 11147625, + 15048832, 15438496, 22745004, 22899924, + 22963194, 23499048, 28622167, 34611139)), strand = rep("+", 12), typeDiff = rep(-1, 12)) + + exp[["iAll"]][[1]] <- GRanges(seqnames = rep("S", 3), ranges = IRanges(start = c(15048832, 22963194, 23499048), + end = c(15048832, 22963194, 23499048)), + strand = rep("+", 3), typeDiff = rep(-1, 3)) + + + message <- paste0("test.interGeneration_good_01() ", + "- Function did not return expected values") + + checkEquals(obs, exp) +} + + +test.interGeneration_good_02 <- function() { + + permutationResultsFile <- system.file("extdata", "permutationResultsForSites.RDS", package="methylInheritance") + permutationResults <- readRDS(permutationResultsFile) + + resultsGR <- methylInheritance:::getGRangesFromMethylDiff(methDiff = permutationResults, pDiff = 11, + qvalue = 0.01, type = "hyper") + + obs <- methylInheritance:::interGeneration(resultsGR) + + exp <- list() + exp[["i2"]] <- list() + exp[["iAll"]] <- list() + + exp[["i2"]][[1]] <- GRanges(seqnames = rep("S", 14), ranges = IRanges(start = c(570115, 2573229, 5063112, 8247138, 8791494, + 9955639, 26798489, 27089337, 27188724, 27236909, + 30222185, 30786437, 33611091, 33886929), + end = c(570115, 2573229, 5063112, 8247138, 8791494, + 9955639, 26798489, 27089337, 27188724, 27236909, + 30222185, 30786437, 33611091, 33886929)), + strand = rep("+", 14), typeDiff = rep(1, 14)) + + exp[["i2"]][[2]] <- GRanges(seqnames = rep("S", 10), ranges = IRanges(start = c(97481, 572272, 3281006, 11121503, 19260516, + 19445653, 22874019, 27232572, 30222185, 35929511), + end = c(97481, 572272, 3281006, 11121503, 19260516, + 19445653, 22874019, 27232572, 30222185, 35929511)), + strand = rep("+", 10), typeDiff = rep(1, 10)) + + exp[["iAll"]][[1]] <- GRanges(seqnames = rep("S", 1), ranges = IRanges(start = c(30222185), + end = c(30222185)), + strand = rep("+", 1), typeDiff = rep(1, 1)) + + + message <- paste0("test.interGeneration_good_02() ", + "- Function did not return expected values") + + checkEquals(obs, exp) +} + diff --git a/inst/unitTests/test_methylInheritanceMethods.R b/inst/unitTests/test_methylInheritanceMethods.R index cd7eb18..e0bdfb9 100644 --- a/inst/unitTests/test_methylInheritanceMethods.R +++ b/inst/unitTests/test_methylInheritanceMethods.R @@ -7,26 +7,30 @@ ## Test the methylInheritanceMethods functions ################################################### -DIRECTORY <- system.file("extdata", package = "methylInheritance") - -METHYL_OBJ_FILE_01 <- dir(system.file("extdata", package = "methylInheritance"), - pattern = "methylObj_001.RDS", full.names = TRUE) +METHYL_OBJ_FILE_01 <- system.file("extdata", "methylObj_001.RDS", + package="methylInheritance") METHYL_OBJ_01 <- readRDS(METHYL_OBJ_FILE_01) -TEST_DIR <- dir(system.file("extdata", package = "methylInheritance"), - pattern = "TEST", full.names = TRUE) +TEST_DIR <- system.file("extdata", "TEST", package="methylInheritance") data("methylInheritanceResults") +.tearDown <- function() { + if (dir.exists("test_002")) { + unlink("test_002", recursive = TRUE, force = TRUE) + } +} + ########################################################### -## runPermutationUsingRDSFile() function +## runPermutation() function ########################################################### -## Test when methylKitRDSFile is not a valid RDS file name -test.runPermutationUsingRDSFile_methylKitRDSFile_not_valid <- function() { - obs <- tryCatch(runPermutationUsingRDSFile( - methylKitRDSFile = "HI", outputDir = NULL, +## Test when methylKitData is not a valid RDS file name +test.runPermutation_methylKitData_not_valid_RDS <- function() { + + obs <- tryCatch(runPermutation( + methylKitData = "HI", outputDir = "test_002", nbrPermutations = 2, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = FALSE, minCovBasesForTiles = 2, @@ -35,31 +39,42 @@ test.runPermutationUsingRDSFile_methylKitRDSFile_not_valid <- function() { exp <- "The file \"HI\" does not exist." - message <- paste0(" test.runPermutationUsingRDSFile_methylKitRDSFile_not_valid() ", - "- Not valid file for methylKitRDSFile did not generated expected message.") + message <- paste0(" test.runPermutation_methylKitData_not_valid_RDS() ", + "- Not valid file for methylKitData did not generated expected message.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, exp, msg=message) } ## Test when all parameters valid -test.runPermutationUsingRDSFile_good_001 <- function() { - obs <- runPermutationUsingRDSFile(methylKitRDSFile = METHYL_OBJ_FILE_01, runObservationAnalysis = FALSE, +test.runPermutation_good_001 <- function() { + + if (!dir.exists("test_002")) { + dir.create("test_002/SITES/", recursive=TRUE) + dir.create("test_002/TILES/", recursive=TRUE) + } + + obs <- runPermutation(methylKitData = METHYL_OBJ_FILE_01, runObservationAnalysis = FALSE, type = "both", nbrPermutations = 2, minReads = 5, minMethDiff = 5, - vSeed = 2021) + outputDir = "test_002", vSeed = 2000) + + obsV <- methylInheritance::loadAllRDSResults(permutationResultsDir = "test_002", + analysisResultsDir = NULL, doingSites = TRUE, + doingTiles = TRUE) + exp <- list() exp[["PERMUTATION"]] <- list() exp[["PERMUTATION"]][[1]] <- list() exp[["PERMUTATION"]][[1]][["SITES"]] <- list() exp[["PERMUTATION"]][[1]][["SITES"]][["i2"]] <- list() - exp[["PERMUTATION"]][[1]][["SITES"]][["i2"]][["HYPER"]] <- list(0,2) - exp[["PERMUTATION"]][[1]][["SITES"]][["i2"]][["HYPO"]] <- list(0,1) + exp[["PERMUTATION"]][[1]][["SITES"]][["i2"]][["HYPER"]] <- list(0,0) + exp[["PERMUTATION"]][[1]][["SITES"]][["i2"]][["HYPO"]] <- list(1,3) exp[["PERMUTATION"]][[1]][["SITES"]][["iAll"]] <- list() exp[["PERMUTATION"]][[1]][["SITES"]][["iAll"]][["HYPER"]] <- list(0) - exp[["PERMUTATION"]][[1]][["SITES"]][["iAll"]][["HYPO"]] <- list(0) + exp[["PERMUTATION"]][[1]][["SITES"]][["iAll"]][["HYPO"]] <- list(1) exp[["PERMUTATION"]][[1]][["TILES"]] <- list() exp[["PERMUTATION"]][[1]][["TILES"]][["i2"]] <- list() exp[["PERMUTATION"]][[1]][["TILES"]][["i2"]][["HYPER"]] <- list(0,0) - exp[["PERMUTATION"]][[1]][["TILES"]][["i2"]][["HYPO"]] <- list(0,0) + exp[["PERMUTATION"]][[1]][["TILES"]][["i2"]][["HYPO"]] <- list(1000,0) exp[["PERMUTATION"]][[1]][["TILES"]][["iAll"]] <- list() exp[["PERMUTATION"]][[1]][["TILES"]][["iAll"]][["HYPER"]] <- list(0) exp[["PERMUTATION"]][[1]][["TILES"]][["iAll"]][["HYPO"]] <- list(0) @@ -67,34 +82,35 @@ test.runPermutationUsingRDSFile_good_001 <- function() { exp[["PERMUTATION"]][[2]][["SITES"]] <- list() exp[["PERMUTATION"]][[2]][["SITES"]][["i2"]] <- list() exp[["PERMUTATION"]][[2]][["SITES"]][["i2"]][["HYPER"]] <- list(0,0) - exp[["PERMUTATION"]][[2]][["SITES"]][["i2"]][["HYPO"]] <- list(2,0) + exp[["PERMUTATION"]][[2]][["SITES"]][["i2"]][["HYPO"]] <- list(0,1) exp[["PERMUTATION"]][[2]][["SITES"]][["iAll"]] <- list() exp[["PERMUTATION"]][[2]][["SITES"]][["iAll"]][["HYPER"]] <- list(0) exp[["PERMUTATION"]][[2]][["SITES"]][["iAll"]][["HYPO"]] <- list(0) exp[["PERMUTATION"]][[2]][["TILES"]] <- list() exp[["PERMUTATION"]][[2]][["TILES"]][["i2"]] <- list() exp[["PERMUTATION"]][[2]][["TILES"]][["i2"]][["HYPER"]] <- list(0,0) - exp[["PERMUTATION"]][[2]][["TILES"]][["i2"]][["HYPO"]] <- list(1000,0) + exp[["PERMUTATION"]][[2]][["TILES"]][["i2"]][["HYPO"]] <- list(0,0) exp[["PERMUTATION"]][[2]][["TILES"]][["iAll"]] <- list() exp[["PERMUTATION"]][[2]][["TILES"]][["iAll"]][["HYPER"]] <- list(0) exp[["PERMUTATION"]][[2]][["TILES"]][["iAll"]][["HYPO"]] <- list(0) - message <- paste0(" test.runPermutationUsingRDSFile_good_001() ", + message <- paste0(" test.runPermutation_good_001() ", "- Valid parameters did not generated expected message.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, 0, msg = message) + checkEquals(obsV$PERMUTATION, exp$PERMUTATION, msg = message) } ########################################################### -# runObservationUsingRDSFile() function +# runObservation() function ########################################################### -## Test when methylKitRDSFile is not a valid RDS file name -test.runObservationUsingRDSFile_methylKitRDSFile_not_valid <- function() { - obs <- tryCatch(runObservationUsingRDSFile( - methylKitRDSFile = "ALLO", outputDir = NULL, - nbrCores = 1, nbrCoresDiffMeth = 1, +## Test when methylKitData is not a valid RDS file name +test.runObservation_methylKitData_not_valid <- function() { + + obs <- tryCatch(runObservation( + methylKitData = "ALLO", outputDir = NULL, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = FALSE, minCovBasesForTiles = 2, tileSize = 1000, stepSize = 100, vSeed = 222), @@ -102,21 +118,29 @@ test.runObservationUsingRDSFile_methylKitRDSFile_not_valid <- function() { exp <- "The file \"ALLO\" does not exist." - message <- paste0(" test.runObservationUsingRDSFile_methylKitRDSFile_not_valid() ", - "- Not valid file for methylKitRDSFile did not generated expected message.") + message <- paste0(" test.runObservation_methylKitData_not_valid() ", + "- Not valid file for methylKitData did not generated expected message.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, exp, msg=message) } ## Test when all parameters valid -test.runObservationUsingRDSFile_good_001 <- function() { - obs <- tryCatch(runObservationUsingRDSFile( - methylKitRDSFile = METHYL_OBJ_FILE_01, type = "sites", - outputDir = NULL, nbrCores = 1, nbrCoresDiffMeth = 1, - minReads = 10, minMethDiff = 5, qvalue = 0.05, - maxPercReads = 99.9, destrand = FALSE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 200), - error=conditionMessage) +test.runObservation_good_001 <- function() { + + if (!dir.exists("test_002")) { + dir.create("test_002/SITES/", recursive=TRUE) + } + + obs <- runObservation( + methylKitData=METHYL_OBJ_FILE_01, type="sites", + outputDir="test_002", nbrCoresDiffMeth=1, + minReads=10, minMethDiff=5, qvalue = 0.05, + maxPercReads=99.9, destrand=FALSE, minCovBasesForTiles=2, + tileSize=1000, stepSize=100, vSeed=200, + saveInfoByGeneration=FALSE) + + obsV <- methylInheritance::loadAllRDSResults(permutationResultsDir=NULL, + analysisResultsDir="test_002") exp <- list() exp[["OBSERVATION"]] <- list() @@ -128,10 +152,11 @@ test.runObservationUsingRDSFile_good_001 <- function() { exp[["OBSERVATION"]][["SITES"]][["iAll"]][["HYPER"]] <- list(0) exp[["OBSERVATION"]][["SITES"]][["iAll"]][["HYPO"]] <- list(2) - message <- paste0(" test.runObservationUsingRDSFile_good_001() ", + message <- paste0(" test.runObservation_good_001() ", "- All valid parameters did not generated expected result.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, 0, msg=message) + checkEquals(obsV$OBSERVATION, exp$OBSERVATION, msg=message) } @@ -141,6 +166,7 @@ test.runObservationUsingRDSFile_good_001 <- function() { # Test result when all parameters are good test.extractInfo_good_01 <- function() { + obs <- tryCatch(extractInfo(allResults = methylInheritanceResults, type = "sites", inter="i2", 1), error=conditionMessage) @@ -154,7 +180,7 @@ test.extractInfo_good_01 <- function() { message <- paste0(" test.extractInfo_good_01() ", "- Valid parameters for formatForGraph did not generated expected results.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, exp, msg=message) } @@ -164,6 +190,7 @@ test.extractInfo_good_01 <- function() { ## Test result when all parameters are good test.loadAllRDSResults_good_01 <- function() { + obs <- tryCatch(loadAllRDSResults(analysisResultsDir = TEST_DIR, permutationResultsDir = TEST_DIR, doingSites = TRUE, doingTiles = TRUE), @@ -209,7 +236,7 @@ test.loadAllRDSResults_good_01 <- function() { "- Valid parameters for loadAllRDSResults() ", "did not generated expected results.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, exp, msg=message) } @@ -236,6 +263,7 @@ test.mergePermutationAndObservation_observation_not_list <- function() { ## Test when permutationResults is not a list test.mergePermutationAndObservation_permutation_not_list <- function() { + res <- list() res[["OBSERVATION"]] <- methylInheritanceResults$OBSERVATION @@ -248,7 +276,7 @@ test.mergePermutationAndObservation_permutation_not_list <- function() { message <- paste0(" test.mergePermutationAndObservation_permutation_not_list() ", "- Not a list for permutationResults did not generated expected results.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, exp, msg=message) } ## Test result when all parameters are good @@ -300,7 +328,7 @@ test.mergePermutationAndObservation_good_01 <- function() { "- Valid parameters for mergePermutationAndObservation() ", "did not generated expected results.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, exp, msg=message) } ########################################################### @@ -318,7 +346,130 @@ test.plotGraph_good_01 <- function() { message <- paste0(" test.plotGraph_good_01() ", "- Valid parameters for plotGraph did not generated expected results.") - checkTrue("gtable" %in% class(obs), msg = message) - checkEquals(class(obs[[1]]), "list", msg = message) - checkEquals(class(obs[[2]]), "data.frame", msg = message) + checkTrue(is(obs, "gtable"), msg=message) + checkTrue(is(obs[[1]], "list"), msg=message) + checkTrue(is(obs[[2]], "data.frame"), msg=message) +} + + +########################################################### +## plotConvergenceGraph() function +########################################################### + +# Test result when all parameters are good +test.plotConvergenceGraph_good_01 <- function() { + + filesDir <- system.file("extdata", "TEST", package="methylInheritance") + + ##Extract convergenc information for F1 and F2 and F3 + data <- loadConvergenceData(analysisResultsDir=filesDir, + permutationResultsDir=filesDir, type="sites", inter="iAll", + position=1, by=1) + + ## Create convergence graph + obs <- plotConvergenceGraph(data) + + message <- paste0(" test.plotConvergenceGraph_good_01() ", + "- Valid parameters for plotGraph did not generated ", + "expected results.") + + checkTrue(is(obs, "ggplot"), msg=message) +} + + +########################################################### +## loadConvergenceData() function +########################################################### + +# Test result when all parameters are good +test.loadConvergenceData_good_01 <- function() { + + filesDir <- system.file("extdata", "TEST", package="methylInheritance") + + ##Extract convergence information for F1 and F2 and F3 + data <- loadConvergenceData(analysisResultsDir=filesDir, + permutationResultsDir=filesDir, + type="sites", inter="iAll", + position=1, by=1) + + expected <- data.frame(NBR_PERMUTATIONS=c(1,1,2,2,3,3), + ELEMENT=rep("SITES", 6), ANALYSIS=rep("iAll", 6), + POSITION=rep(1, 6), TYPE=rep(c("HYPER", "HYPO"), 3), + SIGNIFICANT_LEVEL=c(1.00000000, 1.0000000, 1.0000000000, + 0.666666666666666666, 1.000000000, 0.50000000000000)) + + message <- paste0(" test.loadConvergenceData_good_01() ", + "- Valid parameters for loadConvergenceData did not ", + "generated expected results.") + + checkTrue(is(data, "data.frame"), msg=message) + checkEquals(data , expected, msg=message) +} + + +# Test result when all parameters are good and using 2 different directories +test.loadConvergenceData_two_different_directories <- function() { + + permutationDir <- system.file("extdata", "TEST_01/permutations", + package="methylInheritance") + + observationDir <- system.file("extdata", "TEST_01/observations", + package="methylInheritance") + + ##Extract convergence information for F1 and F2 and F3 + data <- loadConvergenceData(analysisResultsDir = observationDir, + permutationResultsDir = permutationDir, + type = "sites", inter = "iAll", + position = 1, by = 1) + + expected <- data.frame(NBR_PERMUTATIONS=c(1,1,2,2,3,3,4,4,5,5,6,6,7,7,8,8,9,9,10,10), + ELEMENT=rep("SITES", 20), ANALYSIS=rep("iAll", 20), + POSITION=rep(1, 20), TYPE=rep(c("HYPER", "HYPO"), 10), + SIGNIFICANT_LEVEL=c(1.00000000000000000000, 0.50000000000000000000, + 0.66666666666666662966, 0.66666666666666662966, + 0.75000000000000000000, 0.50000000000000000000, + 0.80000000000000004441, 0.40000000000000002220, + 0.83333333333333337034, 0.33333333333333331483, + 0.71428571428571430157, 0.42857142857142854764, + 0.75000000000000000000, 0.37500000000000000000, + 0.77777777777777779011, 0.33333333333333331483, + 0.80000000000000004441, 0.29999999999999998890, + 0.72727272727272729291, 0.27272727272727270709)) + + message <- paste0(" test.loadConvergenceData_two_different_directories() ", + "- Using two different directories for observation and permutation with loadConvergenceData did not generated expected results.") + + checkTrue(is(data, "data.frame"), msg=message) + checkEquals(data , expected, msg=message) +} + + +# Test result when all parameters are good +test.loadConvergenceData_two_different_directories_by_5 <- function() { + + permutationDir <- system.file("extdata", "TEST_01/permutations", + package="methylInheritance") + + observationDir <- system.file("extdata", "TEST_01/observations", + package="methylInheritance") + + ##Extract convergence information for F1 and F2 and F3 + data <- loadConvergenceData(analysisResultsDir = observationDir, + permutationResultsDir = permutationDir, + type = "sites", inter = "iAll", + position = 1, by = 5) + + expected <- data.frame(NBR_PERMUTATIONS=c(5,5,10,10), + ELEMENT=rep("SITES", 4), ANALYSIS=rep("iAll", 4), + POSITION=rep(1, 4), TYPE=rep(c("HYPER", "HYPO"), 2), + SIGNIFICANT_LEVEL=c(0.83333333333333337034, + 0.33333333333333331483, + 0.72727272727272729291, + 0.27272727272727270709)) + + message <- paste0(" test.loadConvergenceData_two_different_directories() ", + "- Using two different directories for observation and permutation with loadConvergenceData did not generated expected results.") + + checkTrue(is(data, "data.frame"), msg=message) + checkEquals(data , expected, msg=message) } diff --git a/inst/unitTests/test_print_methylInheritanceAllResults.R b/inst/unitTests/test_print_methylInheritanceAllResults.R index 3ba4e9f..f393095 100644 --- a/inst/unitTests/test_print_methylInheritanceAllResults.R +++ b/inst/unitTests/test_print_methylInheritanceAllResults.R @@ -7,16 +7,6 @@ ## Test the print.rjmcmcNucleosomesMerge.R function ################################################### - -### {{{ --- Test setup --- - -if(FALSE) { - library( "RUnit" ) - library( "methylInheritance" ) -} - -### }}} - data("methylInheritanceResults") ########################################################### diff --git a/inst/unitTests/test_validateRunPermutationUsingRDS.R b/inst/unitTests/test_validateRunPermutationUsingRDS.R index 185b4b5..ce04917 100644 --- a/inst/unitTests/test_validateRunPermutationUsingRDS.R +++ b/inst/unitTests/test_validateRunPermutationUsingRDS.R @@ -1,252 +1,260 @@ ################################################### - # Created by Astrid Deschenes - # 2016-12-21 - ################################################### ################################################### -## Test the validateRunPermutationUsingMethylKitInfo function +## Test the validateRunPermutation function ################################################### -DIRECTORY <- system.file("extdata", package = "methylInheritance") - -METHYL_OBJ_FILE <- dir(system.file("extdata", package = "methylInheritance"), - pattern = "methylObj_001.RDS", full.names = TRUE) +METHYL_OBJ_FILE <- system.file("extdata", "methylObj_001.RDS", + package="methylInheritance") METHYL_OBJ <- readRDS(METHYL_OBJ_FILE) ########################################################### -## validateRunPermutationUsingMethylKitInfo() function +## validateRunPermutation() function ########################################################### -## Test when methylKitInfo is a string -test.validateRunPermutationUsingMethylKitInfo_methylKitInfo_string <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = "HI", outputDir = NULL, runObservedAnalysis = TRUE, +## Test when methylKitData is a string +test.validateRunPermutation_methylKitData_number <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = 33, outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 2, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) - exp <- paste0("methylKitInfo must be a list containing \"methylRawList\" ", + exp <- paste0("methylKitData must be a list containing \"methylRawList\" ", "entries; each entry must contain all \"methylRaw\" objects ", "related to one generation") - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_methylKitInfo_string() ", - "- Not valid methylKitInfo did not generated expected message.") + message <- paste0(" test.validateRunPermutation_methylKitData_number() ", + "- Not valid methylKitData did not generated expected message.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, exp, msg=message) } -## Test when methylKitInfo is a list of integers -test.validateRunPermutationUsingMethylKitInfo_methylKitInfo_list_of_int <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = list(a=c(1,2), b=c(2,2)), type = "sites", outputDir = NULL, +## Test when methylKitData is a list of integers +test.validateRunPermutation_methylKitData_list_of_int <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = list(a=c(1,2), b=c(2,2)), type = "sites", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 2, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) - exp <- paste0("methylKitInfo must be a list containing \"methylRawList\" ", + exp <- paste0("methylKitData must be a list containing \"methylRawList\" ", "entries; each entry must contain all \"methylRaw\" objects ", "related to one generation") - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_methylKitInfo_list_of_int() ", - "- Not valid methylKitInfo did not generated expected message.") + message <- paste0(" test.validateRunPermutation_methylKitData_list_of_int() ", + "- Not valid methylKitData did not generated expected message.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, exp, msg=message) } ## Test when outputDir is a number -test.validateRunPermutationUsingMethylKitInfo_outputDir_as_number <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "sites", outputDir = 33, +test.validateRunPermutation_outputDir_as_number <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "sites", outputDir = 33, runObservedAnalysis = TRUE, nbrPermutations = 2, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) - exp <- "output_dir must be a character string or NULL" + exp <- "output_dir must be a character string" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_outputDir_as_number() ", + message <- paste0(" test.validateRunPermutation_outputDir_as_number() ", "- Not valid outputDir did not generated expected message.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, exp, msg=message) } ## Test when runObservedAnalysis is a string -test.validateRunPermutationUsingMethylKitInfo_runObservedAnalysis_string <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, runObservedAnalysis = "allo", +test.validateRunPermutation_runObservedAnalysis_string <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type="both", outputDir = "info", + runObservedAnalysis = "allo", nbrPermutations = 2, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "runObservedAnalysis must be a logical" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_runObservedAnalysis_string() ", + message <- paste0(" test.validateRunPermutation_runObservedAnalysis_string() ", "- Not valid runObservedAnalysis did not generated expected message.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, exp, msg=message) } ## Test when nbrPermutations is a string -test.validateRunPermutationUsingMethylKitInfo_nbrPermutations_as_string <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "sites", outputDir = NULL, +test.validateRunPermutation_nbrPermutations_as_string <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "sites", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = "TOTO", nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "nbrPermutations must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_nbrPermutations_as_string() ", + message <- paste0(" test.validateRunPermutation_nbrPermutations_as_string() ", "- Not valid nbrPermutations did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when nbrCores is zero -test.validateRunPermutationUsingMethylKitInfo_nbrCores_zero <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_nbrCores_zero <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 0, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "nbrCores must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_nbrCores_zero() ", + message <- paste0(" test.validateRunPermutation_nbrCores_zero() ", "- Not valid nbrCores did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when nbrCores is a negative integer -test.validateRunPermutationUsingMethylKitInfo_nbrCores_negative <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_nbrCores_negative <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = FALSE, nbrPermutations = 3, nbrCores = -1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "nbrCores must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_nbrCores_negative() ", + message <- paste0(" test.validateRunPermutation_nbrCores_negative() ", "- Not valid nbrCores did not generated expected message.") - checkEquals(obs, exp, msg = message) + checkEquals(obs, exp, msg=message) } ## Test when nbrCoresDiffMeth is zero -test.validateRunPermutationUsingMethylKitInfo_nbrCoresDiffMeth_zero <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_nbrCoresDiffMeth_zero <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 0, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "nbrCoresDiffMeth must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_nbrCoresDiffMeth_zero() ", + message <- paste0(" test.validateRunPermutation_nbrCoresDiffMeth_zero() ", "- Not valid nbrCoresDiffMeth did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when nbrCoresDiffMeth is a negative integer -test.validateRunPermutationUsingMethylKitInfo_nbrCoresDiffMeth_negative <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_nbrCoresDiffMeth_negative <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = -1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "nbrCoresDiffMeth must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_nbrCoresDiffMeth_negative() ", + message <- paste0(" test.validateRunPermutation_nbrCoresDiffMeth_negative() ", "- Not valid nbrCoresDiffMeth did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when minReads is zero -test.validateRunPermutationUsingMethylKitInfo_minReads_zero <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_minReads_zero <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 0, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "minReads must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_minReads_zero() ", + message <- paste0(" test.validateRunPermutation_minReads_zero() ", "- Not valid minReads did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when minReads is negative -test.validateRunPermutationUsingMethylKitInfo_minReads_negative <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_minReads_negative <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = -1, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "minReads must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_minReads_negative() ", + message <- paste0(" test.validateRunPermutation_minReads_negative() ", "- Not valid minReads did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when minMethDiff is negative -test.validateRunPermutationUsingMethylKitInfo_minMethDiff_negative <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_minMethDiff_negative <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff =-0.1, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "minMethDiff must be a positive double between [0,100]" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_minMethDiff_negative() ", + message <- paste0(" test.validateRunPermutation_minMethDiff_negative() ", "- Not valid minMethDiff did not generated expected message.") checkEquals(obs, exp, msg = message) @@ -254,113 +262,119 @@ test.validateRunPermutationUsingMethylKitInfo_minMethDiff_negative <- function() ## Test when minMethDiff is above 100 -test.validateRunPermutationUsingMethylKitInfo_minMethDiff_above_100 <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_minMethDiff_above_100 <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 100.1, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "minMethDiff must be a positive double between [0,100]" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_minMethDiff_above_100() ", + message <- paste0(" test.validateRunPermutation_minMethDiff_above_100() ", "- Not valid minMethDiff did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when qvalue is above 1 -test.validateRunPermutationUsingMethylKitInfo_qvalue_above_1 <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_qvalue_above_1 <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 1.01, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "qvalue must be a positive double between [0,1]" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_qvalue_above_1() ", + message <- paste0(" test.validateRunPermutation_qvalue_above_1() ", "- Not valid qvalue did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when qvalue is negative -test.validateRunPermutationUsingMethylKitInfo_qvalue_negative <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_qvalue_negative <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = -0.01, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "qvalue must be a positive double between [0,1]" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_qvalue_negative() ", + message <- paste0(" test.validateRunPermutation_qvalue_negative() ", "- Not valid qvalue did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when maxPercReads is not a number -test.validateRunPermutationUsingMethylKitInfo_maxPercReads_not_number <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_maxPercReads_not_number <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = "lala", destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "maxPercReads must be a positive double between [0,100]" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_maxPercReads_not_number() ", + message <- paste0(" test.validateRunPermutation_maxPercReads_not_number() ", "- Not valid maxPercReads did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when maxPercReads is above 100 -test.validateRunPermutationUsingMethylKitInfo_maxPercReads_above_100 <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, runObservedAnalysis = TRUE, +test.validateRunPermutation_maxPercReads_above_100 <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 100.1, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "maxPercReads must be a positive double between [0,100]" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_maxPercReads_above_100() ", + message <- paste0(" test.validateRunPermutation_maxPercReads_above_100() ", "- Not valid maxPercReads did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when maxPercReads is negative -test.validateRunPermutationUsingMethylKitInfo_maxPercReads_negative <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_maxPercReads_negative <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = -0.1, destrand = TRUE, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "maxPercReads must be a positive double between [0,100]" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_maxPercReads_negative() ", + message <- paste0(" test.validateRunPermutation_maxPercReads_negative() ", "- Not valid maxPercReads did not generated expected message.") checkEquals(obs, exp, msg = message) @@ -368,19 +382,20 @@ test.validateRunPermutationUsingMethylKitInfo_maxPercReads_negative <- function( ## Test when destrand is a number -test.validateRunPermutationUsingMethylKitInfo_destrand_number <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, type = "both", outputDir = NULL, +test.validateRunPermutation_destrand_number <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, type = "both", outputDir = "info", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = 20, minCovBasesForTiles = 2, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "destrand must be a logical" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_destrand_number() ", + message <- paste0(" test.validateRunPermutation_destrand_number() ", "- Not valid destrand did not generated expected message.") checkEquals(obs, exp, msg = message) @@ -388,76 +403,80 @@ test.validateRunPermutationUsingMethylKitInfo_destrand_number <- function() { ## Test when minCovBasesForTiles is a string and type is both -test.validateRunPermutationUsingMethylKitInfo_minCovBasesForTiles_string_type_both <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "both", +test.validateRunPermutation_minCovBasesForTiles_string_type_both <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "both", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = "ici", - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "minCovBasesForTiles must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_minCovBasesForTiles_string_type_both() ", + message <- paste0(" test.validateRunPermutation_minCovBasesForTiles_string_type_both() ", "- Not valid minCovBasesForTiles did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when minCovBasesForTiles is negative and type is both -test.validateRunPermutationUsingMethylKitInfo_minCovBasesForTiles_negative_type_both <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "both", +test.validateRunPermutation_minCovBasesForTiles_negative_type_both <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "both", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = -1, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "minCovBasesForTiles must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_minCovBasesForTiles_negative_type_both() ", + message <- paste0(" test.validateRunPermutation_minCovBasesForTiles_negative_type_both() ", "- Not valid minCovBasesForTiles did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when minCovBasesForTiles is a string and type is tiles -test.validateRunPermutationUsingMethylKitInfo_minCovBasesForTiles_string_type_tiles <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "tiles", +test.validateRunPermutation_minCovBasesForTiles_string_type_tiles <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "tiles", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = "a", - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, restartCalculation = FALSE, + saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "minCovBasesForTiles must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_minCovBasesForTiles_string_type_tiles() ", + message <- paste0(" test.validateRunPermutation_minCovBasesForTiles_string_type_tiles() ", "- Not valid minCovBasesForTiles did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when minCovBasesForTiles is negative and type is tiles -test.validateRunPermutationUsingMethylKitInfo_minCovBasesForTiles_negative_type_tiles <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "tiles", +test.validateRunPermutation_minCovBasesForTiles_negative_type_tiles <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "tiles", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = -1, - tileSize = 1000, stepSize = 100, vSeed = 222), + tileSize = 1000, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "minCovBasesForTiles must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_minCovBasesForTiles_negative_type_tiles() ", + message <- paste0(" test.validateRunPermutation_minCovBasesForTiles_negative_type_tiles() ", "- Not valid minCovBasesForTiles did not generated expected message.") checkEquals(obs, exp, msg = message) @@ -465,76 +484,81 @@ test.validateRunPermutationUsingMethylKitInfo_minCovBasesForTiles_negative_type_ ## Test when tileSize is a string and type is both -test.validateRunPermutationUsingMethylKitInfo_tileSize_string_type_both <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "both", +test.validateRunPermutation_tileSize_string_type_both <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "both", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = "yes", stepSize = 100, vSeed = 222), + tileSize = "yes", stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "tileSize must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_minCovBasesForTiles_string_type_both() ", + message <- paste0(" test.validateRunPermutation_minCovBasesForTiles_string_type_both() ", "- Not valid tileSize did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when tileSize is zero and type is both -test.validateRunPermutationUsingMethylKitInfo_tileSize_zero_type_both <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "both", +test.validateRunPermutation_tileSize_zero_type_both <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "both", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = 0, stepSize = 100, vSeed = 222), + tileSize = 0, stepSize = 100, vSeed = 222, restartCalculation = FALSE, + saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "tileSize must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_tileSize_zero_type_both() ", + message <- paste0(" test.validateRunPermutation_tileSize_zero_type_both() ", "- Not valid tileSize did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when tileSize is negative and type is both -test.validateRunPermutationUsingMethylKitInfo_tileSize_negative_type_both <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "both", +test.validateRunPermutation_tileSize_negative_type_both <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "both", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = -1, stepSize = 100, vSeed = 222), + tileSize = -1, stepSize = 100, vSeed = 222, restartCalculation = FALSE, + saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "tileSize must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_tileSize_negative_type_both() ", + message <- paste0(" test.validateRunPermutation_tileSize_negative_type_both() ", "- Not valid tileSize did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when tileSize is a string and type is tiles -test.validateRunPermutationUsingMethylKitInfo_tileSize_string_type_tiles <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "tiles", +test.validateRunPermutation_tileSize_string_type_tiles <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "tiles", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = "yes", stepSize = 100, vSeed = 222), + tileSize = "yes", stepSize = 100, vSeed = 222, + restartCalculation = FALSE, + saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "tileSize must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_tileSize_string_type_tiles() ", + message <- paste0(" test.validateRunPermutation_tileSize_string_type_tiles() ", "- Not valid tileSize did not generated expected message.") checkEquals(obs, exp, msg = message) @@ -542,209 +566,260 @@ test.validateRunPermutationUsingMethylKitInfo_tileSize_string_type_tiles <- func ## Test when tileSize is zero and type is tiles -test.validateRunPermutationUsingMethylKitInfo_tileSize_zero_type_tiles <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "tiles", +test.validateRunPermutation_tileSize_zero_type_tiles <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "tiles", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = 0, stepSize = 100, vSeed = 222), + tileSize = 0, stepSize = 100, vSeed = 222, restartCalculation = FALSE, + saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "tileSize must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_tileSize_zero_type_tiles() ", + message <- paste0(" test.validateRunPermutation_tileSize_zero_type_tiles() ", "- Not valid tileSize did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when tileSize is negative and type is tiles -test.validateRunPermutationUsingMethylKitInfo_tileSize_negative_type_tiles <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "tiles", +test.validateRunPermutation_tileSize_negative_type_tiles <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "tiles", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = -1, stepSize = 100, vSeed = 222), + tileSize = -1, stepSize = 100, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "tileSize must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_tileSize_negative_type_tiles() ", + message <- paste0(" test.validateRunPermutation_tileSize_negative_type_tiles() ", "- Not valid tileSize did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when stepSize is a string and type is tiles -test.validateRunPermutationUsingMethylKitInfo_stepSize_string_type_tiles <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "tiles", +test.validateRunPermutation_stepSize_string_type_tiles <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "tiles", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = 10000, stepSize = "one", vSeed = 222), + tileSize = 10000, stepSize = "one", vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "stepSize must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_stepSize_string_type_tiles() ", + message <- paste0(" test.validateRunPermutation_stepSize_string_type_tiles() ", "- Not valid stepSize did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when stepSize is zero and type is tiles -test.validateRunPermutationUsingMethylKitInfo_stepSizee_zero_type_tiles <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "tiles", +test.validateRunPermutation_stepSizee_zero_type_tiles <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "tiles", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = 10000, stepSize = 0, vSeed = 222), + tileSize = 10000, stepSize = 0, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "stepSize must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_stepSizee_zero_type_tiles() ", + message <- paste0(" test.validateRunPermutation_stepSizee_zero_type_tiles() ", "- Not valid stepSize did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when stepSize is negative and type is tiles -test.validateRunPermutationUsingMethylKitInfo_stepSize_negative_type_tiles <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "tiles", +test.validateRunPermutation_stepSize_negative_type_tiles <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "tiles", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = 10000, stepSize = -1, vSeed = 222), + tileSize = 10000, stepSize = -1, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "stepSize must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_stepSize_negative_type_tiles() ", + message <- paste0(" test.validateRunPermutation_stepSize_negative_type_tiles() ", "- Not valid stepSize did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when stepSize is a string and type is both -test.validateRunPermutationUsingMethylKitInfo_stepSize_string_type_both <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "both", +test.validateRunPermutation_stepSize_string_type_both <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "titi", type = "both", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = 10000, stepSize = "one", vSeed = 222), + tileSize = 10000, stepSize = "one", vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "stepSize must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_stepSize_string_type_both() ", + message <- paste0(" test.validateRunPermutation_stepSize_string_type_both() ", "- Not valid stepSize did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when stepSize is zero and type is both -test.validateRunPermutationUsingMethylKitInfo_stepSizee_zero_type_both <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "both", +test.validateRunPermutation_stepSizee_zero_type_both <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "toto", type = "both", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = 10000, stepSize = 0, vSeed = 222), + tileSize = 10000, stepSize = 0, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "stepSize must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_stepSizee_zero_type_both() ", + message <- paste0(" test.validateRunPermutation_stepSizee_zero_type_both() ", "- Not valid stepSize did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when stepSize is negative and type is both -test.validateRunPermutationUsingMethylKitInfo_stepSize_negative_type_both <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "both", +test.validateRunPermutation_stepSize_negative_type_both <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "titi", type = "both", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = 10000, stepSize = -1, vSeed = 222), + tileSize = 10000, stepSize = -1, vSeed = 222, + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "stepSize must be a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_stepSize_negative_type_both() ", + message <- paste0(" test.validateRunPermutation_stepSize_negative_type_both() ", "- Not valid stepSize did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when vSeed is a string -test.validateRunPermutationUsingMethylKitInfo_vSeed_string <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "both", +test.validateRunPermutation_vSeed_string <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "toto", type = "both", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = 10000, stepSize = 100, vSeed = "222"), + tileSize = 10000, stepSize = 100, vSeed = "222", + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "vSeed must be either -1 or a positive integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_vSeed_string() ", + message <- paste0(" test.validateRunPermutation_vSeed_string() ", "- Not valid vSeed did not generated expected message.") checkEquals(obs, exp, msg = message) } ## Test when vSeed is a string -test.validateRunPermutationUsingMethylKitInfo_vSeed_string <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "both", +test.validateRunPermutation_vSeed_string <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "fofo", type = "both", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, - tileSize = 10000, stepSize = 100, vSeed = "33"), + tileSize = 10000, stepSize = 100, vSeed = "33", + restartCalculation = FALSE, saveInfoByGeneration = FALSE), error=conditionMessage) exp <- "vSeed must be an integer or numeric" - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_vSeed_string() ", + message <- paste0(" test.validateRunPermutation_vSeed_string() ", "- Not valid vSeed did not generated expected message.") checkEquals(obs, exp, msg = message) } +## Test when restartCalculation is a string +test.validateRunPermutation_restartCalculation_string <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "info", type = "both", + runObservedAnalysis = TRUE, + nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, + minReads = 10, minMethDiff = 10, qvalue = 0.05, + maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, + tileSize = 10000, stepSize = 100, vSeed = 22, + restartCalculation = "TRUE", saveInfoByGeneration = FALSE), + error=conditionMessage) + + exp <- "restartCalculation must be a logical" + + message <- paste0(" test.validateRunPermutation_restartCalculation_string() ", + "- Not valid restartCalculation did not generated expected message.") + + checkEquals(obs, exp, msg = message) +} + +## Test when saveInfoByGeneration is a string +test.validateRunPermutation_saveInfoByGeneration_string <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "file", type = "both", + runObservedAnalysis = TRUE, + nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, + minReads = 10, minMethDiff = 10, qvalue = 0.05, + maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, + tileSize = 10000, stepSize = 100, vSeed = 22, + restartCalculation = TRUE, saveInfoByGeneration = "FALSE"), + error=conditionMessage) + + exp <- "saveInfoByGeneration must be a logical" + + message <- paste0(" test.validateRunPermutation_saveInfoByGeneration_string() ", + "- Not valid saveInfoByGeneration did not generated expected message.") + + checkEquals(obs, exp, msg = message) +} + ## Test when all parameters valid -test.validateRunPermutationUsingMethylKitInfo_all_valid_parameters_01 <- function() { - obs <- tryCatch(methylInheritance:::validateRunPermutationUsingMethylKitInfo( - methylKitInfo = METHYL_OBJ, outputDir = NULL, type = "sites", +test.validateRunPermutation_all_valid_parameters_01 <- function() { + obs <- tryCatch(methylInheritance:::validateRunPermutation( + methylKitData = METHYL_OBJ, outputDir = "TOTO", type = "sites", runObservedAnalysis = TRUE, nbrPermutations = 3, nbrCores = 1, nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.05, maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = -3, - tileSize = -1, stepSize = -2, vSeed = 22), + tileSize = -1, stepSize = -2, vSeed = 22, restartCalculation = FALSE, + saveInfoByGeneration = FALSE), error=conditionMessage) exp <- 0 - message <- paste0(" test.validateRunPermutationUsingMethylKitInfo_all_valid_parameters_01() ", + message <- paste0(" test.validateRunPermutation_all_valid_parameters_01() ", "- All valid parameters did not generated expected message.") checkEquals(obs, exp, msg = message) diff --git a/man/calculateSignificantLevel.Rd b/man/calculateSignificantLevel.Rd new file mode 100644 index 0000000..34e2af6 --- /dev/null +++ b/man/calculateSignificantLevel.Rd @@ -0,0 +1,49 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/methylInheritanceInternalMethods.R +\name{calculateSignificantLevel} +\alias{calculateSignificantLevel} +\title{Calculate significant level for hypo and hyper conserved elements} +\usage{ +calculateSignificantLevel(formatForGraphDataFrame) +} +\arguments{ +\item{formatForGraphDataFrame}{a \code{data.frame} containing the +observation results (using real +data) and the permutation results (using shuffled data). Both hyper and +hypo differentially conserved methylation results must be present. The +\code{data.frame} must have 3 columns : "TYPE", "RESULT" and "SOURCE". +The "TYPE" can be either "HYPER" or "HYPO". The "RESULT" is the number +of conserved differentially elements. The "SOURCE" can be either +"OBSERVATION" or "PERMUTATION".} +} +\value{ +a list containing two elements: +\itemize{ +\item \code{HYPER} a \code{double}, the significant level for the +hyper differentially methylated conserved elements +\item \code{HYPO} a \code{double}, the significant level for the +hypo differentially methylated conserved elements +} +} +\description{ +Calculate significant level for hypo and hyper conserved +elements using permutation results as well as observed results +} +\examples{ + +## Loading dataset containing all results +data(methylInheritanceResults) + +## Extract information for the intersection between conserved differentially +## methylated sites (type = sites) between the intersection of 2 +## generations (inter = i2): F2 and F3 (position = 2) +info <- extractInfo(allResults = methylInheritanceResults, + type = "sites", inter="i2", 2) + +## Create graph +methylInheritance:::calculateSignificantLevel(info) + +} +\author{ +Astrid Deschenes, Pascal Belleau +} diff --git a/man/createDataStructure.Rd b/man/createDataStructure.Rd index 888294f..654e156 100644 --- a/man/createDataStructure.Rd +++ b/man/createDataStructure.Rd @@ -72,12 +72,11 @@ separatly. \examples{ ## Get the name of the directory where the file is stored -filesDir <- dir(system.file("extdata", package = "methylInheritance"), -pattern = "TEST", full.names = TRUE) +filesDir <- system.file("extdata", "TEST", package="methylInheritance") ## Load file containing results from a observation analysis obsResults <- readRDS(file = paste0(filesDir, -"/SITES/SITES_observed_results.RDS")) + "/SITES/SITES_observed_results.RDS")) ## Create data structure using information form the observation analysis formatedResults <- methylInheritance:::createDataStructure(obsResults) @@ -87,4 +86,3 @@ formatedResults <- methylInheritance:::createDataStructure(obsResults) Astrid Deschenes, Pascal Belleau } \keyword{internal} - diff --git a/man/createOutputDir.Rd b/man/createOutputDir.Rd index c9d8c06..a01e080 100644 --- a/man/createOutputDir.Rd +++ b/man/createOutputDir.Rd @@ -5,7 +5,12 @@ \title{Create directories that will contained the results of the permutations in RDS format} \usage{ -createOutputDir(outputDir, doingSites = TRUE, doingTiles = FALSE) +createOutputDir( + outputDir, + doingSites = TRUE, + doingTiles = FALSE, + saveInfoByGeneration +) } \arguments{ \item{outputDir}{a string of \code{character}, the name of the main @@ -18,6 +23,11 @@ results of the permutation analysis for sites is created when \item{doingTiles}{a \code{logical}, a directory consecrated to contain the results of the permutation analysis for tiles is created when \code{doingTiles} = \code{TRUE}. Default: \code{FALSE}.} + +\item{saveInfoByGeneration}{a \code{logical}, when \code{TRUE}, the +information about differentially methylated sites and tiles for each +generation is saved in a RDS file. The information is saved in a different +file for each permutation.} } \value{ \code{0} when all directories are created without problem. @@ -29,12 +39,11 @@ permutations in RDS format. \examples{ ## Create an output directory for SITES only -\dontrun{createOutputDir(outputDir = "testSites", doingSites = TRUE, -doingTiles = FALSE)} +methylInheritance:::createOutputDir(outputDir = "testSites", + doingSites = TRUE, doingTiles = FALSE, saveInfoByGeneration = TRUE) } \author{ Astrid Deschenes } \keyword{internal} - diff --git a/man/demoForTransgenerationalAnalysis.Rd b/man/demoForTransgenerationalAnalysis.Rd index 043d6e8..f802942 100644 --- a/man/demoForTransgenerationalAnalysis.Rd +++ b/man/demoForTransgenerationalAnalysis.Rd @@ -3,14 +3,16 @@ \docType{data} \name{demoForTransgenerationalAnalysis} \alias{demoForTransgenerationalAnalysis} -\title{Methylation information from samples over three generations. Information +\title{The methylation information from samples over three generations. Information for each generation is stored in a \code{methylRawList} format (for demo purpose).} -\format{A \code{list} containing three \code{methylRawList} objects. Each +\format{ +A \code{list} containing three \code{methylRawList} objects. Each \code{methylRawList} contains the information for one generation (first entry = first generation, etc..). Each sample information is stored in a \code{methylRaw} object. There is \code{methylRaw} objects -(6 controls and 6 cases) in each generation.} +(6 controls and 6 cases) in each generation. +} \usage{ data(demoForTransgenerationalAnalysis) } @@ -22,16 +24,15 @@ stored in a \code{methylRaw} object. There is \code{methylRaw} objects (6 controls and 6 cases) in each generation. } \description{ -The object is a \code{list} with 3 entries. Each entry correspond to the +The object is a \code{list} with 3 entries. Each entry corresponds to the information for one generation (first entry = first generation, etc..) -stored in a \code{methylRawList} ojbect. -There is 12 samples (6 controls and 6 cases) for each generation. Each +stored in a \code{methylRawList} object. +There are 12 samples (6 controls and 6 cases) for each generation. Each sample information is stored in a \code{methylRaw} object. } \details{ -This dataset can be -used to test \code{runPermutationUsingMethylKitInfo} and -{runObservationUsingMethylKitInfo} functions. +This dataset can be used to test \code{runPermutation} and +\code{runObservation} functions. } \examples{ @@ -39,18 +40,27 @@ used to test \code{runPermutationUsingMethylKitInfo} and data(demoForTransgenerationalAnalysis) ## Run a permutation analysis -\dontrun{(runObservationUsingMethylKitInfo(methylKitInfo = -demoForTransgenerationalAnalysis, type = "tiles", nbrPermutations = 3, -vSeed = 2001)} +runObservation(methylKitData = demoForTransgenerationalAnalysis, + outputDir = "test_demo", type = "tiles", vSeed = 2001) + +## Get results +result <- loadAllRDSResults(analysisResultsDir = "test_demo", + permutationResultsDir = NULL, doingSites = FALSE, + doingTiles = TRUE) + +## Remove result directory +if (dir.exists("test_demo")) { + unlink("test_demo", recursive = TRUE) +} } \seealso{ -\itemize{ - \item \code{\link{runPermutationUsingMethylKitInfo}} {for running a - permutation analysis using methylKit info entry} - \item \code{\link{runObservationUsingMethylKitInfo}} {for running a +\describe{ + \item{\code{\link{runPermutation}}}{ for running a + permutation analysis, and optionally an observation analysis, + using a multi-generational dataset} + \item{\code{\link{runObservation}}}{ for running an observation analysis using methylKit info entry} } } \keyword{datasets} - diff --git a/man/extractInfo.Rd b/man/extractInfo.Rd index 2e14200..cda2738 100644 --- a/man/extractInfo.Rd +++ b/man/extractInfo.Rd @@ -5,19 +5,22 @@ \title{Extract the information specific to a subsection of the permutation analysis} \usage{ -extractInfo(allResults, type = c("sites", "tiles"), inter = c("i2", "iAll"), - position) +extractInfo( + allResults, + type = c("sites", "tiles"), + inter = c("i2", "iAll"), + position = 1 +) } \arguments{ \item{allResults}{a \code{list} of class \code{methylInheritanceAllResults} as created by the -\code{runPermutationUsingMethylKitInfo} or the -\code{runPermutationUsingRDSFile} functions. The \code{list} must contain +\code{runPermutation} function. The \code{list} must contain two entries : \code{"PERMUTATION"} and \code{"OBSERVATION"}. The \code{"PERMUTATION"} \code{list} must contain all results from all permutations while the \code{"OBSERVATION"} \code{list} must contain the result obtained with -the observed dataset (not permutated).} +the observed dataset (not shuffled).} \item{type}{One of the \code{"sites"} or \code{"tiles"} strings. Specifies the type @@ -34,39 +37,36 @@ generations or more \code{inter} = \code{"iAll"}. Default: \code{"i2"}.} \item{position}{a positive \code{integer}, the position in the \code{list} -where the information will be extracted.} +where the information will be extracted. Default=\code{1}.} } \value{ a \code{data.frame} containing the observation results (using real -data) and the permutation results (using permutated data). Both hyper and +data) and the permutation results (using shuffled data). Both hyper and hypo differentially conserved methylation results are present. } \description{ Extract the information specific to a subsection of the permutation analysis. The extracted information will be specific to one -type of differentially methylation analysis (tiles or sites), to one type +type of differential methylation analysis (tiles or sites), to one type of intersection (two consecutive generation or more) and to one specific group of generations. } \examples{ ## Get the name of the directory where files are stored -filesDir <- dir(system.file("extdata", package = "methylInheritance"), -pattern = "TEST", full.names = TRUE) +filesDir <- system.file("extdata", "TEST", package="methylInheritance") ## Load information from files results <- loadAllRDSResults(analysisResultsDir = filesDir, -permutationResultsDir = filesDir, doingSites = TRUE, doingTiles = TRUE) + permutationResultsDir = filesDir, doingSites = TRUE, doingTiles = TRUE) ## Extract information for the intersection between conserved differentially ## methylated sites (type = sites) between the intersection of 2 ## generations (inter = i2): F1 and F2 (position = 1) -info <- extractInfo(allResults = results, -type = "sites", inter="i2", 1) +info <- extractInfo(allResults = results, type = "sites", inter="i2", 1) } \author{ Astrid Deschenes, Pascal Belleau } - diff --git a/man/formatInputMethylData.Rd b/man/formatInputMethylData.Rd new file mode 100644 index 0000000..9b2b154 --- /dev/null +++ b/man/formatInputMethylData.Rd @@ -0,0 +1,36 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/methylInheritanceInternalMethods.R +\name{formatInputMethylData} +\alias{formatInputMethylData} +\title{Permute dataset} +\usage{ +formatInputMethylData(methylKitData) +} +\arguments{ +\item{methylKitData}{a \code{list} of \code{methylRawList} entries. Each +\code{methylRawList} entry must contain all the \code{methylRaw} entries +related to one generation (first entry = first generation, second +entry = second generation, etc..). The number of generations must +correspond to the number +of entries in the \code{methylKitData}. At least 2 generations +must be present to make a permutation analysis. More information can be +found in the methylKit package.} +} +\value{ +a \code{list} of \code{methylRawList} entries. +} +\description{ +Permute dataset and format it to be ready for an analysis +} +\examples{ + +## Load dataset +data("samplesForTransgenerationalAnalysis") + +methylInheritance:::formatInputMethylData(samplesForTransgenerationalAnalysis) + +} +\author{ +Astrid Deschenes, Pascal Belleau +} +\keyword{internal} diff --git a/man/getGRangesFromMethylDiff.Rd b/man/getGRangesFromMethylDiff.Rd index c62bb42..79e63e7 100644 --- a/man/getGRangesFromMethylDiff.Rd +++ b/man/getGRangesFromMethylDiff.Rd @@ -5,8 +5,12 @@ \title{Transform results from a CpG site or region analysis done on mutliple generations into a \code{list} of \code{GRanges} objects} \usage{ -getGRangesFromMethylDiff(methDiff, pDiff, qvalue, type = c("all", "hyper", - "hypo")) +getGRangesFromMethylDiff( + methDiff, + pDiff, + qvalue, + type = c("all", "hyper", "hypo") +) } \arguments{ \item{methDiff}{a \code{list} of S4 \code{methylDiff} class objects, each @@ -44,18 +48,16 @@ represent a CpG site or region analysis done on one generation. \examples{ ## Load permutation results on sites -permutationResultsFile <- dir(system.file("extdata", -package = "methylInheritance"), pattern = "permutationResultsForSites.RDS", -full.names = TRUE) +permutationResultsFile <- system.file("extdata", + "permutationResultsForSites.RDS", package="methylInheritance") permutationResults <- readRDS(permutationResultsFile) ## Transform result to GRanges resultsGR <- methylInheritance:::getGRangesFromMethylDiff(methDiff = -permutationResults, pDiff = 10, qvalue = 0.01, type = "hyper") + permutationResults, pDiff = 10, qvalue = 0.01, type = "hyper") } \author{ Pascal Belleau } \keyword{internal} - diff --git a/man/interGeneration.Rd b/man/interGeneration.Rd index 5247d22..8726aad 100644 --- a/man/interGeneration.Rd +++ b/man/interGeneration.Rd @@ -44,14 +44,13 @@ each entry represents the results for one generation. \examples{ ## Load permutation results on sites -permutationResultsFile <- dir(system.file("extdata", -package = "methylInheritance"), pattern = "permutationResultsForSites.RDS", -full.names = TRUE) +permutationResultsFile <- system.file("extdata", + "permutationResultsForSites.RDS", package="methylInheritance") permutationResults <- readRDS(permutationResultsFile) ## Transform result to GRanges resultsGR <- methylInheritance:::getGRangesFromMethylDiff(methDiff = -permutationResults, pDiff = 10, qvalue = 0.01, type = "hyper") + permutationResults, pDiff = 10, qvalue = 0.01, type = "hyper") ## Extract inter generational conserved sites conservedSitesGR <- methylInheritance:::interGeneration(resultsGR) @@ -61,4 +60,3 @@ conservedSitesGR <- methylInheritance:::interGeneration(resultsGR) Pascal Belleau, Astrid Deschenes } \keyword{internal} - diff --git a/man/isInterGenerationResults.Rd b/man/isInterGenerationResults.Rd new file mode 100644 index 0000000..be58e50 --- /dev/null +++ b/man/isInterGenerationResults.Rd @@ -0,0 +1,48 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/methylInheritanceInternalMethods.R +\name{isInterGenerationResults} +\alias{isInterGenerationResults} +\title{Verify if a specific file containing intergenerational results +exists or not.} +\usage{ +isInterGenerationResults(outputDir, permutationID, type = c("sites", "tiles")) +} +\arguments{ +\item{outputDir}{a string of \code{character}, the name of the directory +that will contain +the results of the permutation. The name should end with a slash. The +directory should already exists.} + +\item{permutationID}{an \code{integer}, the identifier of the permutation. +When the \code{permutationID} = \code{0}, the results are considered as the +observed results and are saved in a file with the "_observed_results.RDS" +extension. When the \code{permutationID} != \code{0}, the results are +considered as permutation results and are saved in a file with the +"_permutation_permutationID.RDS" extension where permutationID is the +identifier of the permutation.} + +\item{type}{One of the \code{"sites"} or \code{"tiles"} strings. Specifies +the type of differentially methylated elements should be saved. +Default: \code{"sites"}.} +} +\value{ +\code{TRUE} when file present; otherwise \code{FALSE}. +} +\description{ +Verify if a specific file containing intergenerational results +exists or not. +} +\examples{ + +## Get the name of the directory where the file is stored +filesDir <- system.file("extdata", "TEST", package="methylInheritance") + +## Verify that DMS intergenerational results for the observed data exists +methylInheritance:::isInterGenerationResults(outputDir = + paste0(filesDir, "/"), 0, "sites") + +} +\author{ +Astrid Deschenes, Pascal Belleau +} +\keyword{internal} diff --git a/man/loadAllRDSResults.Rd b/man/loadAllRDSResults.Rd index 6a46292..74052f1 100644 --- a/man/loadAllRDSResults.Rd +++ b/man/loadAllRDSResults.Rd @@ -5,17 +5,24 @@ \title{Load all RDS files created by the permutation and observation analysis} \usage{ -loadAllRDSResults(analysisResultsDir, permutationResultsDir, - doingSites = TRUE, doingTiles = FALSE) +loadAllRDSResults( + analysisResultsDir, + permutationResultsDir, + doingSites = TRUE, + doingTiles = FALSE, + maxID = NA +) } \arguments{ \item{analysisResultsDir}{a \code{character} string, the path to the -directory that contains the analysis results. The path can be the same that -for the \code{permutatioNResultsDir} parameter.} +directory that contains the analysis results. The path can be the same as +for the \code{permutationResultsDir} parameter. When \code{NULL}, the +observation results are not loaded. Default = \code{NULL}.} \item{permutationResultsDir}{a \code{character} string, the path to the directory that contains the permutation results. The path can be the same -that for the \code{analysisResultsDir} parameter.} +as for the \code{analysisResultsDir} parameter. When \code{NULL}, the +permutation results are not loaded. Default = \code{NULL}.} \item{doingSites}{a \code{logical}, the data related to differentially methylated sites are loaded when @@ -24,150 +31,15 @@ methylated sites are loaded when \item{doingTiles}{a \code{logical}, the data related to differentially methylated tiles are loaded when \code{doingTiles} = \code{TRUE}. Default: \code{TRUE}.} + +\item{maxID}{\code{NA} or a positive \code{integer}, the maximum +identification number of the permutation files to be loaded. When \code{NA}, +all files present in the directory are loaded. Default: \code{NA}.} } \value{ -a \code{list} of \code{class} "methylInheritanceAllResults" -containing the following elements: -\itemize{ -\item \code{OBSERVATION}, a \code{list} that contains one or two entries. -The possible entries are: -\itemize{ -\item \code{SITES} The results of an analysis by sites, -a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between two consecutive generations. -The first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between two consecutive generations.The -first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -\item \code{TILES} The results of an ananlysis by tiles, a -\code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between two consecutive -generations. The first element represents the intersection of the -first and second generations; the second element, the intersection of -the second and third generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between two consecutive -generations.The first element represents the intersection of the first and -second generations; the second element, the intersection of the second -and third generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -} -\item \code{PERMUTATION} a \code{list} -containing multiple entries. Each entry is the result of one permutation -analysis and contains -a \code{list} with one or two entries. The possible entries are: -\itemize{ -\item \code{SITES} The results of an analysis by sites, a -\code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between two consecutive generations. -The first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between two consecutive generations.The -first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -\item \code{TILES} The results of an analysis by tiles, -a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between two consecutive -generations. The first element represents the intersection of the -first and second generations; the second element, the intersection of -the second and third generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between two consecutive -generations.The first element represents the intersection of the first and -second generations; the second element, the intersection of the second -and third generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -} -} +a \code{list} of class \code{methylInheritanceAllResults} +containing the result of the observation analysis as well as the results +of all the permutations. } \description{ Load all RDS files created by the permutation and @@ -178,15 +50,24 @@ all the pertinent information. \examples{ ## Get the name of the directory where files are stored -filesDir <- dir(system.file("extdata", package = "methylInheritance"), -pattern = "TEST", full.names = TRUE) +filesDir <- system.file("extdata", "TEST", package="methylInheritance") ## Load information from files results <- loadAllRDSResults(analysisResultsDir = filesDir, -permutationResultsDir = filesDir, doingSites = TRUE, doingTiles = TRUE) + permutationResultsDir = filesDir, doingSites = TRUE, doingTiles = TRUE) + +## Print the observation results +results + +## Access the results for the first permutation only for sites +results$PERMUTATION[[1]]$SITES +} +\seealso{ +\code{\link{mergePermutationAndObservation}} for detail +description, in the Value section, of the +\code{methylInheritanceAllResults} object. } \author{ Astrid Deschenes, Pascal Belleau } - diff --git a/man/loadConvergenceData.Rd b/man/loadConvergenceData.Rd new file mode 100644 index 0000000..2b26a2a --- /dev/null +++ b/man/loadConvergenceData.Rd @@ -0,0 +1,65 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/methylInheritanceMethods.R +\name{loadConvergenceData} +\alias{loadConvergenceData} +\title{Load convergence information from RDS files} +\usage{ +loadConvergenceData( + analysisResultsDir, + permutationResultsDir, + type = c("sites", "tiles"), + inter = c("i2", "iAll"), + position, + by = 100 +) +} +\arguments{ +\item{analysisResultsDir}{a \code{character} string, the path to the +directory that contains the analysis results. The path can be the same as +for the \code{permutatioNResultsDir} parameter.} + +\item{permutationResultsDir}{a \code{character} string, the path to the +directory that contains the permutation results. The path can be the same +as for the \code{analysisResultsDir} parameter.} + +\item{type}{One of the \code{"sites"} or \code{"tiles"} strings. +Specifies the type +of differentially methylated elements should be returned. For +retrieving differentially methylated bases \code{type} = \code{"sites"}; for +differentially methylated regions \code{type} = \code{"tiles"}. +Default: \code{"sites"}.} + +\item{inter}{One of the \code{"i2"} or \code{"iAll"} strings. Specifies the +type of intersection should be returned. For +retrieving intersection results between two consecutive generations +\code{inter} = \code{"i2"}; for intersection results between three +generations or more \code{inter} = \code{"iAll"}. +Default: \code{"i2"}.} + +\item{position}{a positive \code{integer}, the position in the \code{list} +where the information will be extracted.} + +\item{by}{a \code{integer}, the increment of the number of permutations +where the significant level is tested. Default: 100.} +} +\value{ +a graph showing the evolution of the significant level with the +number of permutations +} +\description{ +Load convergence information from RDS files. +} +\examples{ + +## Get the name of the directory where files are stored +filesDir <- system.file("extdata", "TEST", package="methylInheritance") + +## Load convergence information +results <- loadConvergenceData(analysisResultsDir = filesDir, + permutationResultsDir = filesDir, type="sites", inter="i2", position=1, + by=1) + +} +\author{ +Astrid Deschenes, Pascal Belleau +} diff --git a/man/mergePermutationAndObservation.Rd b/man/mergePermutationAndObservation.Rd index c6135a9..81922fd 100644 --- a/man/mergePermutationAndObservation.Rd +++ b/man/mergePermutationAndObservation.Rd @@ -16,7 +16,7 @@ the result of one permutation.} \item{observationResults}{a \code{list} with 1 entry called \code{OBSERVATION}. The \code{OBSERVATION} entry is a \code{list} containing the result obtained -with the observed dataset (not permutated).} +with the observed dataset (not shuffled).} } \value{ a \code{list} of class \code{methylInheritanceAllResults} with @@ -24,15 +24,148 @@ a \code{list} of class \code{methylInheritanceAllResults} with \itemize{ \item \code{PERMUTATION} \code{list} with a number of entries corresponding to the number of permutations that have been processed. Each entry contains -the result of one permutation. -\item \code{OBSERVATION} a \code{list} containing the result obtained -with the observed dataset (not permutated). +the result of one permutation.The elements in each entry are: +\itemize{ +\item \code{SITES} Only present when a sites analysis has been achieved, +a \code{list} containing: +\itemize{ +\item\code{i2} a \code{list} containing: +\itemize{ +\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved +hyper differentially methylated sites between two consecutive generations. +The first element represents the intersection of the first and second +generations; the second element, the intersection of the second and third +generations; etc. +\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved +hypo differentially methylated sites between two consecutive generations.The +first element represents the intersection of the first and second +generations; the second element, the intersection of the second and third +generations; etc. +} +\item\code{iAll} a \code{list} containing: +\itemize{ +\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved +hyper differentially methylated sites between three or more consecutive +generations. The first element represents the intersection of the first +three generations; the second element, the intersection of the first fourth +generations; etc.The number of entries depends on the number +of generations. +\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved +hypo differentially methylated sites between three or more consecutive +generations. The first element represents the intersection of the first +three generations; the second element, the intersection of the first fourth +generations; etc. The number of entries depends on the number of +generations. +} +} +\item \code{TILES} Only present when a tiles analysis has been achieved, +a \code{list} containing: +\itemize{ +\item\code{i2} a \code{list} containing: +\itemize{ +\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved +hyper differentially methylated positions between two consecutive +generations. The first element represents the intersection of the +first and second generations; the second element, the intersection of +the second and third generations; etc. +\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved +hypo differentially methylated positions between two consecutive +generations.The first element represents the intersection of the first and +second generations; the second element, the intersection of the second +and third generations; etc. +} +\item\code{iAll} a \code{list} containing: +\itemize{ +\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved +hyper differentially methylated positions between three or more consecutive +generations. The first element represents the intersection of the first +three generations; the second element, the intersection of the first fourth +generations; etc. The number of entries depends on the number +of generations. +\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved +hypo differentially methylated positions between three or more consecutive +generations. The first element represents the intersection of the first +three generations; the second element, the intersection of the first fourth +generations; etc.The number of entries depends on the number of +generations. +} +} +} +\item \code{OBSERVATION} a \code{list} containing +the result obtained with the observed dataset (not shuffled). The +elements are: +\itemize{ +\item \code{SITES} Only present when a sites analysis has been achieved, +a \code{list} containing: +\itemize{ +\item\code{i2} a \code{list} containing: +\itemize{ +\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved +hyper differentially methylated sites between two consecutive generations. +The first element represents the intersection of the first and second +generations; the second element, the intersection of the second and third +generations; etc. +\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved +hypo differentially methylated sites between two consecutive generations.The +first element represents the intersection of the first and second +generations; the second element, the intersection of the second and third +generations; etc. +} +\item\code{iAll} a \code{list} containing: +\itemize{ +\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved +hyper differentially methylated sites between three or more consecutive +generations. The first element represents the intersection of the first +three generations; the second element, the intersection of the first fourth +generations; etc.The number of entries depends on the number +of generations. +\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved +hypo differentially methylated sites between three or more consecutive +generations. The first element represents the intersection of the first +three generations; the second element, the intersection of the first fourth +generations; etc. The number of entries depends on the number of +generations. +} +} +\item \code{TILES} Only present when a tiles analysis has been achieved, +a \code{list} containing: +\itemize{ +\item\code{i2} a \code{list} containing: +\itemize{ +\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved +hyper differentially methylated positions between two consecutive +generations. The first element represents the intersection of the +first and second generations; the second element, the intersection of +the second and third generations; etc. +\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved +hypo differentially methylated positions between two consecutive +generations.The first element represents the intersection of the first and +second generations; the second element, the intersection of the second +and third generations; etc. +} +\item\code{iAll} a \code{list} containing: +\itemize{ +\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved +hyper differentially methylated positions between three or more consecutive +generations. The first element represents the intersection of the first +three generations; the second element, the intersection of the first fourth +generations; etc. The number of entries depends on the number +of generations. +\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved +hypo differentially methylated positions between three or more consecutive +generations. The first element represents the intersection of the first +three generations; the second element, the intersection of the first fourth +generations; etc.The number of entries depends on the number of +generations. +} +} +} } } \description{ Merge the permutation results with the observation results. The merging is only needed when permutation and observation have been -processed separatly. The returned value is a +processed separately. The returned value is a \code{methylInheritanceAllResults} object that can be used by the \code{extractInfo} function. } @@ -43,9 +176,9 @@ observed <- list() observed[["OBSERVATION"]] <- list() observed[["OBSERVATION"]][["SITES"]] <- list() observed[["OBSERVATION"]][["SITES"]][["i2"]] <- list(HYPER = list(11, 10), -HYPO = list(13, 12)) + HYPO = list(13, 12)) observed[["OBSERVATION"]][["SITES"]][["iAll"]] <- list(HYPER = list(1), -HYPO = list(3)) + HYPO = list(3)) ## Create a permutation result containing only 1 permutation result ## Real perumtations results would have more entries @@ -54,16 +187,15 @@ permutated[["PERMUTATION"]] <- list() permutated[["PERMUTATION"]][[1]] <- list() permutated[["PERMUTATION"]][[1]][["SITES"]] <- list() permutated[["PERMUTATION"]][[1]][["SITES"]][["i2"]] <- list(HYPER = -list(11, 12), HYPO = list(8, 11)) + list(11, 12), HYPO = list(8, 11)) permutated[["PERMUTATION"]][[1]][["SITES"]][["iAll"]] <- list(HYPER = -list(0), HYPO = list(1)) + list(0), HYPO = list(1)) ## Merge permutation and observation results mergePermutationAndObservation(permutationResults = permutated, -observationResults = observed) + observationResults = observed) } \author{ Astrid Deschenes, Pascal Belleau } - diff --git a/man/methylInheritance-package.Rd b/man/methylInheritance-package.Rd index dd6cbb6..f9acf4d 100644 --- a/man/methylInheritance-package.Rd +++ b/man/methylInheritance-package.Rd @@ -1,12 +1,16 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/methylInheritance.R \docType{package} +\encoding{UTF-8} \name{methylInheritance-package} -\alias{methylInheritance} \alias{methylInheritance-package} +\alias{methylInheritance} \title{methylInheritance: Permutation-Based Analysis associating Conserved Differentially Methylated Elements from One Generation to the Next to a Treatment Effect} +\value{ +methylInheritance +} \description{ This package does a permutation analysis, based on Monte Carlo sampling, for testing the hypothesis that the number of conserved differentially @@ -14,6 +18,15 @@ methylated elements (sites or tiles), between several generations, is associated to an effect inherited from a treatment and that stochastic effect can be dismissed. } +\seealso{ +\describe{ + \item{\code{\link{runPermutation}}}{ for running a + permutation analysis, and optionally an observation analysis, on a + specified multi-generational dataset} + \item{\code{\link{runObservation}}}{ for running an + observation analysis on a specified multi-generational dataset} +} +} \author{ Astrid Deschênes, Pascal Belleau and @@ -22,19 +35,5 @@ Arnaud Droit Maintainer: Astrid Deschenes } -\seealso{ -\itemize{ - \item \code{\link{runPermutationUsingRDSFile}} {for running a - permutation analysis on the specified multi-generational dataset in - RDS format} - \item \code{\link{runPermutationUsingMethylKitInfo}} {for running a - permutation analysis using a methylKit info object as input} - \item \code{\link{runObservationUsingRDSFile}} {for running a - observation analysis on the specified multi-generational dataset in - RDS format} - \item \code{\link{runObservationUsingMethylKitInfo}} {for running a - observation analysis using a methylKit info object as input} -} -} +\keyword{internal} \keyword{package} - diff --git a/man/methylInheritanceAllResults.Rd b/man/methylInheritanceAllResults.Rd index cd276ac..2f86c29 100644 --- a/man/methylInheritanceAllResults.Rd +++ b/man/methylInheritanceAllResults.Rd @@ -31,4 +31,3 @@ data("methylInheritanceResults") print(methylInheritanceResults) } - diff --git a/man/methylInheritanceResults.Rd b/man/methylInheritanceResults.Rd index c391368..e30bb0c 100644 --- a/man/methylInheritanceResults.Rd +++ b/man/methylInheritanceResults.Rd @@ -4,8 +4,9 @@ \name{methylInheritanceResults} \alias{methylInheritanceResults} \title{All observed and permutation results formatted in a -\code{methylInheritanceResults} class object (for demo purpose).} -\format{a \code{list} of class \code{methylInheritanceAllResults} +\code{methylInheritanceResults} class (for demo purpose).} +\format{ +a \code{list} of class \code{methylInheritanceAllResults} containing the following elements: \itemize{ \item \code{OBSERVATION} a \code{list} containing: @@ -131,7 +132,8 @@ generations. } } } -}} +} +} \usage{ data(methylInheritanceResults) } @@ -158,7 +160,7 @@ The first element represents the intersection of the first and second generations; the second element, the intersection of the second and third generations. } -\item\code{iAll} a \code{list} containing: +\item \code{iAll} a \code{list} containing: \itemize{ \item \code{HYPER} a \code{list} of \code{integer} with 1 entry, the number of conserved @@ -171,7 +173,7 @@ consecutive generations. } \item \code{TILES} a \code{list} containing: \itemize{ -\item\code{i2} a \code{list} containing: +\item \code{i2} a \code{list} containing: \itemize{ \item \code{HYPER} a \code{list} of \code{integer} with 2 entries, the number of conserved @@ -271,8 +273,8 @@ The object is a \code{list} with 2 entries: "OBSERVATION" and } \details{ This dataset can be -used to test the \code{extractInfo} function.The extracted info can be -used to calculate the significant level or to create a graph. +used to test the \code{extractInfo} function.The extracted information can +be used to calculate the significant level or to create a graph. } \examples{ @@ -283,14 +285,13 @@ data(methylInheritanceResults) ## methylated sites (type = sites) between the intersection of 2 ## generations (inter = i2): F1 and F2 (position = 1) extractInfo(allResults = methylInheritanceResults, -type = "sites", inter="i2", 1) + type = "sites", inter="i2", 1) } \seealso{ -\itemize{ - \item \code{\link{extractInfo}} {for extracting the +\describe{ + \item{\code{\link{extractInfo}}}{ for extracting the information specific to a subsection of the permutation analysis} } } \keyword{datasets} - diff --git a/man/plotConvergenceGraph.Rd b/man/plotConvergenceGraph.Rd new file mode 100644 index 0000000..75d8d25 --- /dev/null +++ b/man/plotConvergenceGraph.Rd @@ -0,0 +1,40 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/methylInheritanceMethods.R +\name{plotConvergenceGraph} +\alias{plotConvergenceGraph} +\title{Generate a graph showing the convergence for a permutation analysis} +\usage{ +plotConvergenceGraph(dataFrameConvergence) +} +\arguments{ +\item{dataFrameConvergence}{a \code{data.frame} containing the +significant levels at different number of cycles (total number of +permuted data analysed). The +\code{data.frame} must have 6 columns : "NBR_PERMUTATIONS", "ELEMENT". +"ANALYSIS", "POSITION", "TYPE" and "SIGNIFICANT_LEVEL". The "ELEMENT" can +be either "SITES" or "TILES". The "TYPE" can be either "HYPER" or "HYPO".} +} +\value{ +a \code{ggplot} object. +} +\description{ +Generate a graph showing the convergence for a permutation +analysis using observed and permuted results. +} +\examples{ + +## Get the name of the directory where files are stored +filesDir <- system.file("extdata", "TEST", package="methylInheritance") + +## Extract convergenc information for F1 and F2 and F3 +data <- loadConvergenceData(analysisResultsDir = filesDir, + permutationResultsDir = filesDir, type = "sites", inter = "iAll", + position = 1, by = 1) + +## Create convergence graph +plotConvergenceGraph(data) + +} +\author{ +Astrid Deschenes, Pascal Belleau +} diff --git a/man/plotGraph.Rd b/man/plotGraph.Rd index 777b53d..e45bfa0 100644 --- a/man/plotGraph.Rd +++ b/man/plotGraph.Rd @@ -9,7 +9,7 @@ plotGraph(formatForGraphDataFrame) \arguments{ \item{formatForGraphDataFrame}{a \code{data.frame} containing the observation results (using real -data) and the permutation results (using permutated data). Both hyper and +data) and the permutation results (using shuffled data). Both hyper and hypo differentially conserved methylation results must be present. The \code{data.frame} must have 3 columns : "TYPE", "RESULT" and "SOURCE". The "TYPE" can be either "HYPER" or "HYPO". The "RESULT" is the number @@ -21,7 +21,7 @@ a graph showing the permutation analysis results } \description{ Generate a graph for a permutation analysis using observed -and permutated results. +and shuffled results. } \examples{ @@ -32,7 +32,7 @@ data(methylInheritanceResults) ## methylated sites (type = sites) between the intersection of 2 ## generations (inter = i2): F2 and F3 (position = 2) info <- extractInfo(allResults = methylInheritanceResults, -type = "sites", inter="i2", 2) + type = "sites", inter="i2", 2) ## Create graph plotGraph(info) @@ -41,4 +41,3 @@ plotGraph(info) \author{ Astrid Deschenes, Pascal Belleau } - diff --git a/man/readInterGenerationResults.Rd b/man/readInterGenerationResults.Rd new file mode 100644 index 0000000..f604c75 --- /dev/null +++ b/man/readInterGenerationResults.Rd @@ -0,0 +1,53 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/methylInheritanceInternalMethods.R +\name{readInterGenerationResults} +\alias{readInterGenerationResults} +\title{Read and return intergenerational results contained in a +RDS file} +\usage{ +readInterGenerationResults( + outputDir, + permutationID, + type = c("sites", "tiles") +) +} +\arguments{ +\item{outputDir}{a string of \code{character}, the name of the directory +that will contain +the results of the permutation. The name should end with a slash. The +directory should already exists.} + +\item{permutationID}{an \code{integer}, the identifier of the permutation. +When the \code{permutationID} = \code{0}, the results are considered as the +observed results and are saved in a file with the "_observed_results.RDS" +extension. When the \code{permutationID} != \code{0}, the results are +considered as permutation results and are saved in a file with the +"_permutation_permutationID.RDS" extension. Where permutationID is the +identifier of the permutation.} + +\item{type}{One of the \code{"sites"} or \code{"tiles"} strings. Specifies +the type of differentially methylated elements should be saved. +Default: \code{"sites"}.} +} +\value{ +a \code{list} containing the intergenerational results for the +specified permutation. +} +\description{ +Read and return intergenerational results contained in a +RDS file +} +\examples{ + +## Get the name of the directory where the file is stored +filesDir <- system.file("extdata", "TEST", package="methylInheritance") + +## Read DMS intergenerational results for the observed data +methylInheritance:::readInterGenerationResults(outputDir = + paste0(filesDir, "/"), 0, "sites") + +} +\author{ +Astrid Deschenes, Pascal Belleau +} +\keyword{internal} diff --git a/man/runObservation.Rd b/man/runObservation.Rd new file mode 100644 index 0000000..e3a51a6 --- /dev/null +++ b/man/runObservation.Rd @@ -0,0 +1,154 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/methylInheritanceMethods.R +\name{runObservation} +\alias{runObservation} +\title{Run a differential methylation analysis on multi-generational +dataset} +\usage{ +runObservation( + methylKitData, + type = c("both", "sites", "tiles"), + outputDir = "output", + nbrCoresDiffMeth = 1, + minReads = 10, + minMethDiff = 10, + qvalue = 0.01, + maxPercReads = 99.9, + destrand = FALSE, + minCovBasesForTiles = 0, + tileSize = 1000, + stepSize = 1000, + vSeed = -1, + restartCalculation = FALSE, + saveInfoByGeneration = FALSE +) +} +\arguments{ +\item{methylKitData}{a \code{list} of \code{methylRawList} entries or the +name of the RDS file containing the list. Each +\code{methylRawList} contains all the \code{methylRaw} entries related to +one generation (first entry = first generation, second entry = second +generation, etc..). The number of generations must correspond to the number +of entries in the \code{methylKitData}.At least 2 generations +must be present to calculate the conserved elements. More information can +be found in the methylKit package.} + +\item{type}{One of the "sites","tiles" or "both" strings. Specifies the type +of differentially methylated elements should be returned. For +retrieving differentially methylated bases type="sites"; for +differentially methylated regions type="tiles". Default: "both".} + +\item{outputDir}{a string, the name of the directory that will contain +the results of the analysis. If the directory does not +exist, it will be created. Default: \code{"output"}.} + +\item{nbrCoresDiffMeth}{a positive \code{integer}, the number of cores +to use for parallel differential methylation calculations.The parameter is +used for both sites and tiles analysis. The parameter +corresponds to the \code{num.cores} parameter in the package +\code{methylKit}. +Default: \code{1} and always \code{1} for Windows.} + +\item{minReads}{a positive \code{integer} Bases and regions having lower +coverage than this count are discarded. The parameter +correspond to the \code{lo.count} parameter in the package \code{methylKit}.} + +\item{minMethDiff}{a positive \code{double} between [0,100], the absolute +value of methylation percentage change between cases and controls. The +parameter corresponds to the \code{difference} parameter in +the methylKit package. Default: \code{10}.} + +\item{qvalue}{a positive \code{double} between [0,1], the cutoff +for qvalue of differential methylation statistics. Default: \code{0.01}.} + +\item{maxPercReads}{a \code{double} between [0,100], the percentile of read +counts that is going to be used as an upper cutoff. Bases or regions +having higher +coverage than this percentile are discarded. The parameter is used for +both CpG sites and tiles analysis. The parameter +corresponds to the \code{hi.perc} parameter in the package \code{methylKit}. +Default: \code{99.9}.} + +\item{destrand}{a \code{logical}, when \code{TRUE} will merge reads on both +strands of a CpG dinucleotide to provide better coverage. Only advised +when looking at CpG methylation. Parameter used for both CpG +sites and tiles analysis. +Default: \code{FALSE}.} + +\item{minCovBasesForTiles}{a non-negative \code{integer}, the minimum +number of bases to be covered in a given tiling window. The parameter +corresponds to the \code{cov.bases} parameter in the package +\code{methylKit}. +Only used when \code{doingTiles} = +\code{TRUE}. Default: \code{0}.} + +\item{tileSize}{a positive \code{integer}, the size of the tiling window. +The parameter corresponds to the \code{win.size} parameter in +the package \code{methylKit}. Only +used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} + +\item{stepSize}{a positive \code{integer}, the step size of tiling windows. +The parameter corresponds to the \code{stepSize} parameter in +the package \code{methylKit}. Only +used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} + +\item{vSeed}{a \code{integer}, a seed used when reproducible results are +needed. When a value inferior or equal to zero is given, a random integer +is used. Default: \code{-1}.} + +\item{restartCalculation}{a \code{logical}, when \code{TRUE}, only +permutations that don't have a RDS result final are run. Useful +to restart a permutation analysis that has been interrupted. Beware that +the parameters have to be identical except for this one.} + +\item{saveInfoByGeneration}{a \code{logical}, when \code{TRUE}, the +information about differentially methylated sites and tiles for each +generation is saved in a RDS file. The files are saved in the directory +specified by the \code{outputDir} parameter.} +} +\value{ +\code{0}. +} +\description{ +Run a differential methylation analysis on each generation +present in a dataset. The number of conserved differentially +methylated elements (sites, tile or both) between generations is +them calculated. The +methylKit package is used to identify the differentially methylated +elements. + +The multi-generational dataset or the name of the RDS file that contains +the dataset can be used as input. + +The results can also be saved in RDS file (optional). +} +\examples{ + +## Load methylation information +data(samplesForTransgenerationalAnalysis) + +## Run an observation analysis +runObservation(methylKitData = samplesForTransgenerationalAnalysis, + outputDir = "test", type = "sites", vSeed = 221) + +## Load the results +results <- loadAllRDSResults(analysisResultsDir = "test", + permutationResultsDir = NULL, doingSites = TRUE, doingTiles = FALSE) + +## Print the results +results + +## Remove directory +if (dir.exists("test")) { + unlink("test", recursive = TRUE, force = FALSE) +} + +} +\seealso{ +\code{\link{mergePermutationAndObservation}} for detail +description, in the Value section, of the \code{OBSERVATION} section of the +\code{methylInheritanceAllResults} object. +} +\author{ +Astrid Deschenes, Pascal Belleau +} diff --git a/man/runObservationUsingMethylKitInfo.Rd b/man/runObservationUsingMethylKitInfo.Rd deleted file mode 100644 index f6090a5..0000000 --- a/man/runObservationUsingMethylKitInfo.Rd +++ /dev/null @@ -1,182 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methylInheritanceMethods.R -\name{runObservationUsingMethylKitInfo} -\alias{runObservationUsingMethylKitInfo} -\title{Run a differentially methylation analysis on each generation -present in a dataset} -\usage{ -runObservationUsingMethylKitInfo(methylKitInfo, type = c("both", "sites", - "tiles"), outputDir = NULL, nbrCores = 1, nbrCoresDiffMeth = 1, - minReads = 10, minMethDiff = 10, qvalue = 0.01, maxPercReads = 99.9, - destrand = FALSE, minCovBasesForTiles = 0, tileSize = 1000, - stepSize = 1000, vSeed = -1) -} -\arguments{ -\item{methylKitInfo}{a \code{list} of \code{methylRawList} entries, each -\code{methylRawList} contains all the \code{methylRaw} entries related to -one generation (first entry = first generation, second entry = second -generation, etc..). The number of generations must correspond to the number -of entries in the \code{methylKitInfo}.At least 2 generations -must be present to calculate the conserved elements. More information can -be found in the methylKit package.} - -\item{type}{One of the "sites","tiles" or "both" strings. Specifies the type -of differentially methylated elements should be returned. For -retrieving differentially methylated bases type="sites"; for -differentially methylated regions type="tiles". Default: "both".} - -\item{outputDir}{a string, the name of the directory that will contain -the results of the permutation or \code{NULL}. If the directory does not -exist, it will be created. When \code{NULL}, the results of the permutation -are not saved. Default: \code{NULL}.} - -\item{nbrCores}{a positive \code{integer}, the number of cores to use when -processing the analysis. Default: \code{1} and always \code{1} for Windows.} - -\item{nbrCoresDiffMeth}{a positive \code{integer}, the number of cores -to use for parallel differential methylation calculations.Parameter -used for both sites and tiles analysis. The parameter -corresponds to the \code{num.cores} parameter in the package -\code{methylKit}. -Default: \code{1} and always \code{1} for Windows.} - -\item{minReads}{a positive \code{integer} Bases and regions having lower -coverage than this count are discarded. The parameter -correspond to the \code{lo.count} parameter in the package \code{methylKit}.} - -\item{minMethDiff}{a positive \code{double} betwwen [0,100], the absolute -value of methylation percentage change between cases and controls. The -parameter correspond to the \code{difference} parameter in -the methylKit package. Default: \code{10}.} - -\item{qvalue}{a positive \code{double} betwwen [0,1], the cutoff -for qvalue of differential methylation statistic. Default: \code{0.01}.} - -\item{maxPercReads}{a \code{double} between [0,100], the percentile of read -counts that is going to be used as upper cutoff. Bases ore regions -having higher -coverage than this percentile are discarded. Parameter used for both CpG -sites and tiles analysis. The parameter -correspond to the \code{hi.perc} parameter in the package \code{methylKit}. -Default: \code{99.9}.} - -\item{destrand}{a \code{logical}, when \code{TRUE} will merge reads on both -strands of a CpG dinucleotide to provide better coverage. Only advised -when looking at CpG methylation. Parameter used for both CpG -sites and tiles analysis. -Default: \code{FALSE}.} - -\item{minCovBasesForTiles}{a non-negative \code{integer}, the minimum -number of bases to be covered in a given tiling window. The parameter -corresponds to the \code{cov.bases} parameter in the package -\code{methylKit}. -Only used when \code{doingTiles} = -\code{TRUE}. Default: \code{0}.} - -\item{tileSize}{a positive \code{integer}, the size of the tiling window. -The parameter corresponds to the \code{win.size} parameter in -the package \code{methylKit}. Only -used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} - -\item{stepSize}{a positive \code{integer}, the step size of tiling windows. -The parameter corresponds to the \code{stepSize} parameter in -the package \code{methylKit}. Only -used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} - -\item{vSeed}{a \code{integer}, a seed used when reproducible results are -needed. When a value inferior or equal to zero is given, a random integer -is used. Default: \code{-1}.} -} -\value{ -a \code{list} containing the following elements: -\itemize{ -\item \code{OBSERVATION} a \code{list} containing the following elements: -\itemize{ -\item \code{SITES} Only present when \code{type} = \code{"sites"} or -\code{"both"}, a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between two consecutive generations. -The first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between two consecutive generations.The -first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -\item \code{TILES} Only present when \code{type} = \code{"tiles"} or -\code{"both"}, a \code{list} containing: -itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between two consecutive -generations. The first element represents the intersection of the -first and second generations; the second element, the intersection of -the second and third generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between two consecutive -generations.The first element represents the intersection of the first and -second generations; the second element, the intersection of the second -and third generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -} -} -} -\description{ -Run a differentially methylation analysis on each generation -present in a dataset. The number of conserved differentially -methylated elements (sites, tile or both) is them calculated. The -methylKit package is used to identify the differentially methylated -elements. -} -\examples{ - -## Load methyl information -data(samplesForTransgenerationalAnalysis) - -## Run a permutation analysis -\dontrun{runObservationUsingMethylKitInfo(methylKitInfo = -samplesForTransgenerationalAnalysis, type = "sites", vSeed = 221)} - -} -\author{ -Astrid Deschenes, Pascal Belleau -} - diff --git a/man/runObservationUsingRDSFile.Rd b/man/runObservationUsingRDSFile.Rd deleted file mode 100644 index 3ce671c..0000000 --- a/man/runObservationUsingRDSFile.Rd +++ /dev/null @@ -1,183 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methylInheritanceMethods.R -\name{runObservationUsingRDSFile} -\alias{runObservationUsingRDSFile} -\title{Run a differentially methylation analysis on each generation -present in a dataset} -\usage{ -runObservationUsingRDSFile(methylKitRDSFile, type = c("both", "sites", - "tiles"), outputDir = NULL, nbrCores = 1, nbrCoresDiffMeth = 1, - minReads = 10, minMethDiff = 10, qvalue = 0.01, maxPercReads = 99.9, - destrand = FALSE, minCovBasesForTiles = 0, tileSize = 1000, - stepSize = 1000, vSeed = -1) -} -\arguments{ -\item{methylKitRDSFile}{a string, the name of the RDS file containing the -methylKit objet used for the permutation analysis. The RDS file must -hold a \code{list} of \code{methylRawList} entries, each -\code{methylRawList} contains all the \code{methylRaw} entries related to -one generation (first entry = first generation, second entry = second -generation, etc..). The number of generations must correspond to the number -of entries in the \code{methylKitInfo}.At least 2 generations -must be present to do a permutation analysis. More information can be found -in the methylKit package.} - -\item{type}{One of the "sites","tiles" or "both" strings. Specifies the type -of differentially methylated elements should be returned. For -retrieving differentially methylated bases type="sites"; for -differentially methylated regions type="tiles". Default: "both".} - -\item{outputDir}{a string, the name of the directory that will contain -the results of the permutation or \code{NULL}. If the directory does not -exist, it will be created. When \code{NULL}, the results of the permutation -are not saved. Default: \code{NULL}.} - -\item{nbrCores}{a positive \code{integer}, the number of cores to use when -processing the analysis. Default: \code{1} and always \code{1} for Windows.} - -\item{nbrCoresDiffMeth}{a positive \code{integer}, the number of cores -to use for parallel differential methylation calculations.Parameter -used for both sites and tiles analysis. The parameter -corresponds to the \code{num.cores} parameter in the package -\code{methylKit}. -Default: \code{1} and always \code{1} for Windows.} - -\item{minReads}{a positive \code{integer} Bases and regions having lower -coverage than this count are discarded. The parameter -correspond to the \code{lo.count} parameter in the package \code{methylKit}.} - -\item{minMethDiff}{a positive \code{double} betwwen [0,100], the absolute -value of methylation percentage change between cases and controls. The -parameter correspond to the \code{difference} parameter in -the methylKit package. Default: \code{10}.} - -\item{qvalue}{a positive \code{double} betwwen [0,1], the cutoff -for qvalue of differential methylation statistic. Default: \code{0.01}.} - -\item{maxPercReads}{a \code{double} between [0,100], the percentile of read -counts that is going to be used as upper cutoff. Bases ore regions -having higher -coverage than this percentile are discarded. Parameter used for both CpG -sites and tiles analysis. The parameter -correspond to the \code{hi.perc} parameter in the package \code{methylKit}. -Default: \code{99.9}.} - -\item{destrand}{a \code{logical}, when \code{TRUE} will merge reads on both -strands of a CpG dinucleotide to provide better coverage. Only advised -when looking at CpG methylation. Parameter used for both CpG -sites and tiles analysis. -Default: \code{FALSE}.} - -\item{minCovBasesForTiles}{a non-negative \code{integer}, the minimum -number of bases to be covered in a given tiling window. The parameter -corresponds to the \code{cov.bases} parameter in the package -\code{methylKit}. -Only used when \code{doingTiles} = -\code{TRUE}. Default: \code{0}.} - -\item{tileSize}{a positive \code{integer}, the size of the tiling window. -The parameter corresponds to the \code{win.size} parameter in -the package \code{methylKit}. Only -used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} - -\item{stepSize}{a positive \code{integer}, the step size of tiling windows. -The parameter corresponds to the \code{stepSize} parameter in -the package \code{methylKit}. Only -used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} - -\item{vSeed}{a \code{integer}, a seed used when reproducible results are -needed. When a value inferior or equal to zero is given, a random integer -is used. Default: \code{-1}.} -} -\value{ -@return a \code{list} containing the following elements: -\itemize{ -\item \code{SITES} Only present when \code{type} = \code{"sites"} or -\code{"both"}, a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between two consecutive generations. -The first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between two consecutive generations.The -first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -\item \code{TILES} Only present when \code{type} = \code{"tiles"} or -\code{"both"}, a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between two consecutive -generations. The first element represents the intersection of the -first and second generations; the second element, the intersection of -the second and third generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between two consecutive -generations.The first element represents the intersection of the first and -second generations; the second element, the intersection of the second -and third generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -} -} -\description{ -Run a differentially methylation analysis on each generation -present in a dataset. The number of conserved differentially -methylated elements (sites, tile or both) is them calculated. The -methylKit package is used to identify the differentially methylated -elements. -} -\examples{ - -## Path to a methylKit RDS file -methylFile <- dir(system.file("extdata", package = "methylInheritance"), -pattern = "methylObj_001.RDS", full.names = TRUE) - -## Run a permutation analysis -\dontrun{runObservationUsingRDSFile(methylKitRDSFile = methylFile, -type = "sites", minReads = 8, minMethDiff = 5, -vSeed = 2001)} - -} -\author{ -Astrid Deschenes, Pascal Belleau -} - diff --git a/man/runOnePermutationOnAllGenerations.Rd b/man/runOnePermutationOnAllGenerations.Rd index 72314f6..a4647b4 100644 --- a/man/runOnePermutationOnAllGenerations.Rd +++ b/man/runOnePermutationOnAllGenerations.Rd @@ -5,29 +5,47 @@ \title{Run the analysis on one permutation dataset, including all generations, using \code{methylKit} package} \usage{ -runOnePermutationOnAllGenerations(methylInfoForAllGenerations, - type = c("both", "sites", "tiles"), outputDir = NULL, - nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.01, - maxPercReads = 99.9, destrand = FALSE, minCovBasesForTiles = 0, - tileSize = 1000, stepSize = 1000) +runOnePermutationOnAllGenerations( + id, + methylInfoForAllGenerations, + type = c("both", "sites", "tiles"), + outputDir = NULL, + nbrCoresDiffMeth = 1, + minReads = 10, + minMethDiff = 10, + qvalue = 0.01, + maxPercReads = 99.9, + destrand = FALSE, + minCovBasesForTiles = 0, + tileSize = 1000, + stepSize = 1000, + restartCalculation, + saveInfoByGeneration +) } \arguments{ -\item{methylInfoForAllGenerations}{a \code{list} containing the -following elements: -\itemize{ -\item \code{sample} a \code{list} of \code{methylRawList} entries, each -\code{methylRawList} contains all the \code{methylRaw} entries related to -one generation. The number of generations must correspond to the number -of entries in the \code{methylKitInfo}. At least 2 generations -must be present to do a permutation analysis. -\item \code{id} an integer, the permutation id. -}} +\item{id}{an \code{integer}, the unique identification of the permutation. +When \code{id} is \code{0}, the analysis is done on the real dataset.} + +\item{methylInfoForAllGenerations}{a \code{list} of \code{methylRawList} +entries. Each +\code{methylRawList} entry must contain all the \code{methylRaw} entries +related to one generation (first entry = first generation, second +entry = second generation, etc..). The number of generations must +correspond to the number +of entries in the \code{methylKitData}. At least 2 generations +must be present to make a permutation analysis. More information can be +found in the methylKit package.} \item{type}{One of the "sites","tiles" or "both" strings. Specifies the type of differentially methylated elements should be returned. For retrieving differentially methylated bases type="sites"; for differentially methylated regions type="tiles". Default: "both".} +\item{outputDir}{a string, the name of the directory that will contain +the results of the permutation. If the directory does not +exist, it will be created.} + \item{nbrCoresDiffMeth}{a positive integer, the number of cores to use for parallel differential methylation calculations.Parameter used for both sites and tiles analysis. The parameter @@ -40,11 +58,9 @@ coverage than this count are discarded. The parameter correspond to the \code{lo.count} parameter in the \code{methylKit} package.} \item{minMethDiff}{a positive integer betwwen [0,100], the absolute value -of methylation -percentage change between cases and controls. The parameter +of methylation percentage change between cases and controls. The parameter correspond to the \code{difference} parameter in the -package \code{methylKit}. -Default: \code{10}.} +package \code{methylKit}. Default: \code{10}.} \item{qvalue}{a positive \code{double} inferior to \code{1}, the cutoff for qvalue of differential methylation statistic. Default: \code{0.01}.} @@ -60,15 +76,13 @@ Default: \code{99.9}.} \item{destrand}{a logical, when \code{TRUE} will merge reads on both strands of a CpG dinucleotide to provide better coverage. Only advised when looking at CpG methylation. Parameter used for both -sites and tiles analysis. -Default: \code{FALSE}.} +sites and tiles analysis. Default: \code{FALSE}.} \item{minCovBasesForTiles}{a non-negative integer, the minimum number of bases to be covered in a given tiling window. The parameter corresponds to the \code{cov.bases} parameter in the package \code{methylKit}. -Only used when \code{doingTiles} = -\code{TRUE}. Default: \code{0}.} +Only used when \code{doingTiles} = \code{TRUE}. Default: \code{0}.} \item{tileSize}{a positive integer, the size of the tiling window. The parameter corresponds to the \code{win.size} parameter in @@ -80,11 +94,14 @@ parameter corresponds to the \code{stepSize} parameter in the \code{methylKit} package. Only used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} -\item{doingSites}{a logical, when \code{TRUE} will do the analysis on the -CpG dinucleotide sites. Default: \code{TRUE}.} +\item{restartCalculation}{a \code{logical}, when \code{TRUE}, only +permutations that don't have a RDS result final are run.} -\item{doingTiles}{a logical, when \code{TRUE} will do the analysis on the -tiles. Default: \code{FALSE}.} +\item{saveInfoByGeneration}{a \code{logical}, when \code{TRUE}, the +information about differentially methylated sites and tiles for each +generation is saved in a RDS file. The information is saved in a different +file for each permutation. The files are = saved in the +\code{outputDir}.} } \value{ a \code{list} containing the following elements: @@ -123,7 +140,7 @@ generations. } \item \code{TILES} Only present when \code{type} = \code{"tiles"} or \code{"both"}, a \code{list} containing: -itemize{ +\itemize{ \item\code{i2} a \code{list} containing: \itemize{ \item \code{HYPER} a \code{list} of \code{integer}, the number of conserved @@ -167,18 +184,17 @@ specified. ## Load methyl information data(samplesForTransgenerationalAnalysis) -info <- list(sample = samplesForTransgenerationalAnalysis, id = 100) ## Run a permutation analysis -\dontrun{methylInheritance:::runOnePermutationOnAllGenerations( -methylInfoForAllGenerations = info, type = "sites", outputDir = NULL, -nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.01, -maxPercReads = 99.9, destrand = FALSE, minCovBasesForTiles = 0, -tileSize = 1000, stepSize = 1000)} +methylInheritance:::runOnePermutationOnAllGenerations(id = 2, + methylInfoForAllGenerations = samplesForTransgenerationalAnalysis, + type = "tiles", outputDir = NULL, + nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 10, qvalue = 0.01, + maxPercReads = 99.9, destrand = FALSE, minCovBasesForTiles = 0, + tileSize = 1000, stepSize = 1000, restartCalculation = FALSE) } \author{ Astrid Deschenes, Pascal Belleau } \keyword{internal} - diff --git a/man/runPermutation.Rd b/man/runPermutation.Rd new file mode 100644 index 0000000..1c9dd3e --- /dev/null +++ b/man/runPermutation.Rd @@ -0,0 +1,190 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/methylInheritanceMethods.R +\name{runPermutation} +\alias{runPermutation} +\title{Run all permutations on the specified multi-generational dataset} +\usage{ +runPermutation( + methylKitData, + type = c("both", "sites", "tiles"), + outputDir = "output", + runObservationAnalysis = TRUE, + nbrPermutations = 1000, + nbrCores = 1, + nbrCoresDiffMeth = 1, + minReads = 10, + minMethDiff = 10, + qvalue = 0.01, + maxPercReads = 99.9, + destrand = FALSE, + minCovBasesForTiles = 0, + tileSize = 1000, + stepSize = 1000, + vSeed = -1, + restartCalculation = FALSE, + saveInfoByGeneration = FALSE +) +} +\arguments{ +\item{methylKitData}{a \code{list} of \code{methylRawList} entries or the +name of the RDS file containing the \code{list}. Each +\code{methylRawList} entry must contain all the \code{methylRaw} entries +related to one generation (first entry = first generation, second +entry = second generation, etc..). The number of generations must +correspond to the number +of entries in the \code{methylKitData}. At least 2 generations +must be present to make a permutation analysis. More information can be +found in the methylKit package.} + +\item{type}{One of the "sites","tiles" or "both" strings. Specifies the type +of differentially methylated elements should be returned. For +retrieving differentially methylated bases type="sites"; for +differentially methylated regions type="tiles". Default: "both".} + +\item{outputDir}{a string, the name of the directory that will contain +the results of the permutation. If the directory does not +exist, it will be created. Default: \code{"output"}.} + +\item{runObservationAnalysis}{a \code{logical}, when +\code{runObservationAnalysis} = \code{TRUE}, a CpG analysis on the +observed dataset is done. Default: \code{TRUE}.} + +\item{nbrPermutations, }{a positive \code{integer}, the total number of +permutations that is going to be done. Default: \code{1000}.} + +\item{nbrCores}{a positive \code{integer}, the number of cores to use when +processing the analysis. Default: \code{1} and always \code{1} for Windows.} + +\item{nbrCoresDiffMeth}{a positive \code{integer}, the number of cores +to use for parallel differential methylation calculations. The parameter is +used for both sites and tiles analysis. The parameter +corresponds to the \code{num.cores} parameter in the package +\code{methylKit}. +Default: \code{1} and always \code{1} for Windows.} + +\item{minReads}{a positive \code{integer} Bases and regions having lower +coverage than this count are discarded. The parameter +corresponds to the \code{lo.count} parameter in the package +\code{methylKit}.} + +\item{minMethDiff}{a positive \code{double} between [0,100], the absolute +value of methylation percentage change between cases and controls. The +parameter corresponds to the \code{difference} parameter in +the methylKit package. Default: \code{10}.} + +\item{qvalue}{a positive \code{double} between [0,1], the cutoff +for qvalue of differential methylation statistics. Default: \code{0.01}.} + +\item{maxPercReads}{a \code{double} between [0,100], the percentile of read +counts that is going to be used as an upper cutoff. Bases or regions +having higher +coverage than this percentile are discarded. The parameter is used for +both CpG sites and tiles analysis. The parameter +corresponds to the \code{hi.perc} parameter in the package \code{methylKit}. +Default: \code{99.9}.} + +\item{destrand}{a \code{logical}, when \code{TRUE} will merge reads on both +strands of a CpG dinucleotide to provide better coverage. Only advised +when looking at CpG methylation. The parameter is used for both CpG +sites and tiles analysis. +Default: \code{FALSE}.} + +\item{minCovBasesForTiles}{a non-negative \code{integer}, the minimum +number of bases to be covered in a given tiling window. The parameter +corresponds to the \code{cov.bases} parameter in the package +\code{methylKit}. +Only used when \code{doingTiles} = +\code{TRUE}. Default: \code{0}.} + +\item{tileSize}{a positive \code{integer}, the size of the tiling window. +The parameter corresponds to the \code{win.size} parameter in +the package \code{methylKit}. Only +used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} + +\item{stepSize}{a positive \code{integer}, the step size of tiling windows. +The parameter corresponds to the \code{stepSize} parameter in +the package \code{methylKit}. Only +used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} + +\item{vSeed}{a \code{integer}, a seed used when reproducible results are +needed. When a value inferior or equal to zero is given, a random integer +is used. Default: \code{-1}.} + +\item{restartCalculation}{a \code{logical}, when \code{TRUE}, only +permutations that don't have an associated RDS result file are run. Useful +to restart a permutation analysis that has been interrupted. Beware that +the parameters have to be identical except for this one.} + +\item{saveInfoByGeneration}{a \code{logical}, when \code{TRUE}, the +information about differentially methylated sites and tiles for each +generation is saved in a RDS file. The information is saved in a different +file for each permutation. The files are saved in the directory specified +by the \code{outputDir} parameter.} +} +\value{ +\code{0}. +} +\description{ +Run a permutation analysis, based on Monte Carlo sampling, +for testing the hypothesis that the number of conserved differentially +methylated elements (sites, tiles or both), between +several generations, is associated to an effect inherited from a treatment +and that stochastic effect can be dismissed. + +The multi-generational dataset or the name of the RDS file that contains the +dataset can be used as input. + +The observation analysis can also be run (optional). All permutation +results are saved in RDS files. +} +\examples{ + +## Load methylKit information +data(samplesForTransgenerationalAnalysis) + +## Run a permutation analysis using the methylKit dataset +## A real analysis would require a much higher number of permutations +runPermutation(methylKitData = samplesForTransgenerationalAnalysis, + outputDir = "test_01", runObservationAnalysis = FALSE, type = "sites", + nbrPermutations = 2, vSeed = 221) + +## Get results +results_01 <- loadAllRDSResults(analysisResultsDir = NULL, + permutationResultsDir = "test_01", doingSites = TRUE, + doingTiles = FALSE) + +## Remove results directory +if (dir.exists("test_01")) { + unlink("test_01", recursive = TRUE, force = TRUE) +} + +## Path to a methylKit RDS file +methylFile <- system.file("extdata", "methylObj_001.RDS", + package = "methylInheritance") + +## Run a permutation analysis using RDS file name +## A real analysis would require a much higher number of permutations +runPermutation(methylKitData = methylFile, type = "tiles", + outputDir = "test_02", nbrPermutations = 2, minCovBasesForTiles = 10, + vSeed = 2001) + +## Get results +results_02 <- loadAllRDSResults(analysisResultsDir = NULL, + permutationResultsDir = "test_02", doingSites = FALSE, + doingTiles = TRUE) + +## Remove results directory +if (dir.exists("test_02")) { + unlink("test_02", recursive = TRUE, force = TRUE) +} + +} +\seealso{ +\code{\link{mergePermutationAndObservation}} for detail +description, in the Value section, of the +\code{methylInheritanceAllResults} object as +well as its \code{PERMUTATION} section. +} +\author{ +Astrid Deschenes, Pascal Belleau +} diff --git a/man/runPermutationUsingMethylKitInfo.Rd b/man/runPermutationUsingMethylKitInfo.Rd deleted file mode 100644 index 4394725..0000000 --- a/man/runPermutationUsingMethylKitInfo.Rd +++ /dev/null @@ -1,266 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methylInheritanceMethods.R -\name{runPermutationUsingMethylKitInfo} -\alias{runPermutationUsingMethylKitInfo} -\title{Run all permutations on the specified multi-generational dataset in -RDS format} -\usage{ -runPermutationUsingMethylKitInfo(methylKitInfo, type = c("both", "sites", - "tiles"), outputDir = NULL, runObservationAnalysis = TRUE, - nbrPermutations = 1000, nbrCores = 1, nbrCoresDiffMeth = 1, - minReads = 10, minMethDiff = 10, qvalue = 0.01, maxPercReads = 99.9, - destrand = FALSE, minCovBasesForTiles = 0, tileSize = 1000, - stepSize = 1000, vSeed = -1) -} -\arguments{ -\item{methylKitInfo}{a \code{list} of \code{methylRawList} entries, each -\code{methylRawList} contains all the \code{methylRaw} entries related to -one generation (first entry = first generation, second entry = second -generation, etc..). The number of generations must correspond to the number -of entries in the \code{methylKitInfo}.At least 2 generations -must be present to do a permutation analysis. More information can be found -in the methylKit package.} - -\item{type}{One of the "sites","tiles" or "both" strings. Specifies the type -of differentially methylated elements should be returned. For -retrieving differentially methylated bases type="sites"; for -differentially methylated regions type="tiles". Default: "both".} - -\item{outputDir}{a string, the name of the directory that will contain -the results of the permutation or \code{NULL}. If the directory does not -exist, it will be created. When \code{NULL}, the results of the permutation -are not saved. Default: \code{NULL}.} - -\item{runObservationAnalysis}{a \code{logical}, when -\code{runObservationAnalysis} = \code{TRUE}, a CpG analysis on the -observed dataset is done. Default: \code{TRUE}.} - -\item{nbrPermutations, }{a positive \code{integer}, the total number of -permutations that is going to be done. Default: \code{1000}.} - -\item{nbrCores}{a positive \code{integer}, the number of cores to use when -processing the analysis. Default: \code{1} and always \code{1} for Windows.} - -\item{nbrCoresDiffMeth}{a positive \code{integer}, the number of cores -to use for parallel differential methylation calculations.Parameter -used for both sites and tiles analysis. The parameter -corresponds to the \code{num.cores} parameter in the package -\code{methylKit}. -Default: \code{1} and always \code{1} for Windows.} - -\item{minReads}{a positive \code{integer} Bases and regions having lower -coverage than this count are discarded. The parameter -correspond to the \code{lo.count} parameter in the package \code{methylKit}.} - -\item{minMethDiff}{a positive \code{double} betwwen [0,100], the absolute -value of methylation percentage change between cases and controls. The -parameter correspond to the \code{difference} parameter in -the methylKit package. Default: \code{10}.} - -\item{qvalue}{a positive \code{double} betwwen [0,1], the cutoff -for qvalue of differential methylation statistic. Default: \code{0.01}.} - -\item{maxPercReads}{a \code{double} between [0,100], the percentile of read -counts that is going to be used as upper cutoff. Bases ore regions -having higher -coverage than this percentile are discarded. Parameter used for both CpG -sites and tiles analysis. The parameter -correspond to the \code{hi.perc} parameter in the package \code{methylKit}. -Default: \code{99.9}.} - -\item{destrand}{a \code{logical}, when \code{TRUE} will merge reads on both -strands of a CpG dinucleotide to provide better coverage. Only advised -when looking at CpG methylation. Parameter used for both CpG -sites and tiles analysis. -Default: \code{FALSE}.} - -\item{minCovBasesForTiles}{a non-negative \code{integer}, the minimum -number of bases to be covered in a given tiling window. The parameter -corresponds to the \code{cov.bases} parameter in the package -\code{methylKit}. -Only used when \code{doingTiles} = -\code{TRUE}. Default: \code{0}.} - -\item{tileSize}{a positive \code{integer}, the size of the tiling window. -The parameter corresponds to the \code{win.size} parameter in -the package \code{methylKit}. Only -used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} - -\item{stepSize}{a positive \code{integer}, the step size of tiling windows. -The parameter corresponds to the \code{stepSize} parameter in -the package \code{methylKit}. Only -used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} - -\item{vSeed}{a \code{integer}, a seed used when reproducible results are -needed. When a value inferior or equal to zero is given, a random integer -is used. Default: \code{-1}.} -} -\value{ -a \code{list} of class \code{} when a \code{runObservationAnalysis} -= \code{TRUE}; otherwise a \code{list}. The returned \code{list} -containing the following elements: -\itemize{ -\item \code{OBSERVATION} Only present when \code{runObservationAnalysis} = -\code{TRUE}, a \code{list} containing: -\itemize{ -\item \code{SITES} Only present when \code{type} = \code{"sites"} or -\code{"both"}, a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between two consecutive generations. -The first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between two consecutive generations.The -first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -\item \code{TILES} Only present when \code{type} = \code{"tiles"} or -\code{"both"}, a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between two consecutive -generations. The first element represents the intersection of the -first and second generations; the second element, the intersection of -the second and third generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between two consecutive -generations.The first element represents the intersection of the first and -second generations; the second element, the intersection of the second -and third generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -} -\item \code{PERMUTATION} a \code{list} -containing \code{nbrPermutations} entries. Each entry is -a \code{list} containing: -\itemize{ -\item \code{SITES} Only present when \code{type} = \code{"sites"} or -\code{"both"}, a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between two consecutive generations. -The first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between two consecutive generations.The -first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -\item \code{TILES} Only present when \code{type} = \code{"tiles"} or -\code{"both"}, a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between two consecutive -generations. The first element represents the intersection of the -first and second generations; the second element, the intersection of -the second and third generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between two consecutive -generations.The first element represents the intersection of the first and -second generations; the second element, the intersection of the second -and third generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -} -} -} -\description{ -Run a permutation analysis, based on Monte Carlo sampling, -for testing the hypothesis that the number of conserved differentially -methylated elements (sites, tiles or both), between -several generations, is associated to an effect inherited from a treatment -and that stochastic effect can be dismissed. - -The observation analysis can also be run (optional). All permutation -results can also be saved in RDS files (optional). -} -\examples{ - -## Load methyl information -data(samplesForTransgenerationalAnalysis) - -## Run a permutation analysis -\dontrun{runPermutationUsingMethylKitInfo(methylKitInfo = -samplesForTransgenerationalAnalysis, type = "sites", -nbrPermutations = 3, vSeed = 221)} - -} -\author{ -Astrid Deschenes, Pascal Belleau -} - diff --git a/man/runPermutationUsingRDSFile.Rd b/man/runPermutationUsingRDSFile.Rd deleted file mode 100644 index a33460e..0000000 --- a/man/runPermutationUsingRDSFile.Rd +++ /dev/null @@ -1,269 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methylInheritanceMethods.R -\name{runPermutationUsingRDSFile} -\alias{runPermutationUsingRDSFile} -\title{Run all permutations on the specified multi-generational dataset in -RDS format} -\usage{ -runPermutationUsingRDSFile(methylKitRDSFile, type = c("both", "sites", - "tiles"), outputDir = NULL, runObservationAnalysis = TRUE, - nbrPermutations = 1000, nbrCores = 1, nbrCoresDiffMeth = 1, - minReads = 10, minMethDiff = 10, qvalue = 0.01, maxPercReads = 99.9, - destrand = FALSE, minCovBasesForTiles = 0, tileSize = 1000, - stepSize = 1000, vSeed = -1) -} -\arguments{ -\item{methylKitRDSFile}{a string, the name of the RDS file containing the -methylKit objet used for the permutation analysis. The RDS file must -hold a \code{list} of \code{methylRawList} entries, each -\code{methylRawList} contains all the \code{methylRaw} entries related to -one generation (first entry = first generation, second entry = second -generation, etc..). The number of generations must correspond to the number -of entries in the \code{methylKitInfo}.At least 2 generations -must be present to do a permutation analysis. More information can be found -in the methylKit package} - -\item{type}{One of the "sites","tiles" or "both" strings. Specifies the type -of differentially methylated elements should be returned. For -retrieving differentially methylated bases \code{type} = \code{"sites"}; -for differentially methylated regions type="tiles". Default: "both".} - -\item{outputDir}{a string, the name of the directory that will contain -the results of the permutation or \code{NULL}. If the directory does not -exist, it will be created. When \code{NULL}, the results of the permutation -are not saved. Default: \code{NULL}.} - -\item{runObservationAnalysis}{a \code{logical}, when -\code{runObservationAnalysis} -= \code{TRUE}, a CpG analysis on the observed dataset is done. Default: -\code{TRUE}.} - -\item{nbrPermutations, }{a positive \code{integer}, the total number of -permutations that is going to be done. Default: \code{1000}.} - -\item{nbrCores}{a positive \code{integer}, the number of cores to use when -processing the analysis. Default: \code{1} and always \code{1} for Windows.} - -\item{nbrCoresDiffMeth}{a positive \code{integer}, the number of cores -to use for parallel differential methylation calculations.Parameter -used for both sites and tiles analysis. The parameter -corresponds to the \code{num.cores} parameter in the package -\code{methylKit}. -Default: \code{1} and always \code{1} for Windows.} - -\item{minReads}{a positive \code{integer} Bases and regions having lower -coverage than this count are discarded. The parameter -correspond to the \code{lo.count} parameter in the package \code{methylKit}.} - -\item{minMethDiff}{a positive \code{double} betwwen [0,100], the absolute -value of methylation percentage change between cases and controls. The -parameter correspond to the \code{difference} parameter in -the package \code{methylKit}. Default: \code{10}.} - -\item{qvalue}{a positive \code{double} betwwen [0,1], the cutoff -for qvalue of differential methylation statistic. Default: \code{0.01}.} - -\item{maxPercReads}{a \code{double} between [0,100], the percentile of read -counts that is going to be used as upper cutoff. Bases ore regions -having higher -coverage than this percentile are discarded. Parameter used for both CpG -sites and tiles analysis. The parameter -correspond to the \code{hi.perc} parameter in the package \code{methylKit}. -Default: \code{99.9}.} - -\item{destrand}{a \code{logical}, when \code{TRUE} will merge reads on both -strands of a CpG dinucleotide to provide better coverage. Only advised -when looking at CpG methylation. Parameter used for both CpG -sites and tiles analysis. -Default: \code{FALSE}.} - -\item{minCovBasesForTiles}{a non-negative \code{integer}, the minimum -number of bases to be covered in a given tiling window. The parameter -corresponds to the \code{cov.bases} parameter in the package -\code{methylKit}. -Only used when \code{doingTiles} = -\code{TRUE}. Default: \code{0}.} - -\item{tileSize}{a positive \code{integer}, the size of the tiling window. -The parameter corresponds to the \code{win.size} parameter in -the package \code{methylKit}. Only -used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} - -\item{stepSize}{a positive \code{integer}, the step size of tiling windows. -The parameter corresponds to the \code{stepSize} parameter in -the package \code{methylKit}. Only -used when \code{doingTiles} = \code{TRUE}. Default: \code{1000}.} - -\item{vSeed}{a \code{integer}, a seed used when reproducible results are -needed. When a value inferior or equal to zero is given, a random integer -is used. Default: \code{-1}.} -} -\value{ -a \code{list} of class \code{} when a \code{runObservationAnalysis} -= \code{TRUE}; otherwise a \code{list}. The returned \code{list} -containing the following elements: -\itemize{ -\item \code{OBSERVATION} Only present when \code{runObservationAnalysis} = -\code{TRUE}, a \code{list} containing: -\itemize{ -\item \code{SITES} Only present when \code{type} = \code{"sites"} or -\code{"both"}, a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between two consecutive generations. -The first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between two consecutive generations.The -first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -\item \code{TILES} Only present when \code{type} = \code{"tiles"} or -\code{"both"}, a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between two consecutive -generations. The first element represents the intersection of the -first and second generations; the second element, the intersection of -the second and third generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between two consecutive -generations.The first element represents the intersection of the first and -second generations; the second element, the intersection of the second -and third generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -} -\item \code{PERMUTATION} a \code{list} -containing \code{nbrPermutations} entries. Each entry is -a \code{list} containing: -\itemize{ -\item \code{SITES} Only present when \code{type} = \code{"sites"} or -\code{"both"}, a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between two consecutive generations. -The first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between two consecutive generations.The -first element represents the intersection of the first and second -generations; the second element, the intersection of the second and third -generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated sites between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -\item \code{TILES} Only present when \code{type} = \code{"tiles"} or -\code{"both"}, a \code{list} containing: -\itemize{ -\item\code{i2} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between two consecutive -generations. The first element represents the intersection of the -first and second generations; the second element, the intersection of -the second and third generations; etc.. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between two consecutive -generations.The first element represents the intersection of the first and -second generations; the second element, the intersection of the second -and third generations; etc.. -} -\item\code{iAll} a \code{list} containing: -\itemize{ -\item \code{HYPER} a \code{list} of \code{integer}, the number of conserved -hyper differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number -of generations. -\item \code{HYPO} a \code{list} of \code{integer}, the number of conserved -hypo differentially methylated positions between three or more consecutive -generations. The first element represents the intersection of the first -three generations; the second element, the intersection of the first fourth -generations; etc..The number of entries depends of the number of -generations. -} -} -} -} -} -\description{ -Run a permutation analysis, based on Monte Carlo sampling, -for testing the hypothesis that the number of conserved differentially -methylated elements (sites, tiles or both), between -several generations, is associated to an effect inherited from a treatment -and that stochastic effect can be dismissed. - -The observation analysis can also be run (optional). All permutation -results can also be saved in RDS files (optional). -} -\examples{ - -## Path to a methylKit RDS file -methylFile <- dir(system.file("extdata", package = "methylInheritance"), -pattern = "methylObj_001.RDS", full.names = TRUE) - -## Run a permutation analysis -\dontrun{runPermutationUsingRDSFile(methylKitRDSFile = methylFile, -type = "sites", nbrPermutations = 10, vSeed = 2001)} - -} -\author{ -Astrid Deschenes, Pascal Belleau -} - diff --git a/man/samplesForTransgenerationalAnalysis.Rd b/man/samplesForTransgenerationalAnalysis.Rd index a3b4576..f3ef2f8 100644 --- a/man/samplesForTransgenerationalAnalysis.Rd +++ b/man/samplesForTransgenerationalAnalysis.Rd @@ -5,11 +5,13 @@ \alias{samplesForTransgenerationalAnalysis} \title{All samples information, formated by \code{methylKit}, in a \code{methylRawList} format (for demo purpose).} -\format{A \code{list} containing three \code{methylRawList} objects. Each +\format{ +A \code{list} containing three \code{methylRawList} objects. Each \code{methylRawList} contains the information for one generation (first entry = first generation, etc..). Each sample information is stored in a \code{methylRaw} object. There is \code{methylRaw} objects -(6 controls and 6 cases) in each generation.} +(6 controls and 6 cases) in each generation. +} \usage{ data(samplesForTransgenerationalAnalysis) } @@ -21,15 +23,15 @@ stored in a \code{methylRaw} object. There is \code{methylRaw} objects (6 controls and 6 cases) in each generation. } \description{ -The object is a \code{list} with 3 entries. Each entry correspond to the +The object is a \code{list} with 3 entries. Each entry corresponds to the information for one generation (first entry = first generation, etc..) stored in a \code{methylRawList}. -There is 12 samples (6 controls and 6 cases) for each generation. Each +There are 12 samples (6 controls and 6 cases) for each generation. Each sample information is stored in a \code{methylRaw} object. } \details{ This dataset can be -used to test the \code{runPermutationUsingMethylKitInfo} function. +used to test the \code{runPermutation} function. } \examples{ @@ -37,16 +39,15 @@ used to test the \code{runPermutationUsingMethylKitInfo} function. data(samplesForTransgenerationalAnalysis) ## Run a permutation analysis -\dontrun{runPermutationUsingMethylKitInfo(methylKitInfo = -samplesForTransgenerationalAnalysis, type = "sites", nbrPermutations = 3, -vSeed = 2001)} +runPermutation(methylKitData = samplesForTransgenerationalAnalysis, + type = "tiles", nbrPermutations = 2, vSeed = 2332) } \seealso{ -\itemize{ - \item \code{\link{runPermutationUsingMethylKitInfo}} {for running a - permutation analysis using methylKit info entry} +\describe{ + \item{\code{\link{runPermutation}}}{ for running a + permutation analysis, and optionally an observation analysis, using + multi-generational dataset} } } \keyword{datasets} - diff --git a/man/saveInterGenerationResults.Rd b/man/saveInterGenerationResults.Rd index 672d066..2056047 100644 --- a/man/saveInterGenerationResults.Rd +++ b/man/saveInterGenerationResults.Rd @@ -3,11 +3,15 @@ \name{saveInterGenerationResults} \alias{saveInterGenerationResults} \title{Save the result of on CpG site or tile analysis on all generations. -The anaysis can come from observed or permutated dataset. Each case is +The anaysis can come from observed or shuffled dataset. Each case is saved with a different extension.} \usage{ -saveInterGenerationResults(outputDir, permutationID, type = c("sites", - "tiles"), interGenerationResult) +saveInterGenerationResults( + outputDir, + permutationID, + type = c("sites", "tiles"), + interGenerationResult +) } \arguments{ \item{outputDir}{a string of \code{character}, the name of the directory @@ -15,27 +19,21 @@ that will contain the results of the permutation. The name should end with a slash. The directory should already exists.} -\item{permutationID}{an \code{integer}, the identifiant of the permutation. +\item{permutationID}{an \code{integer}, the identifier of the permutation. When the \code{permutationID} = \code{0}, the results are considered as the observed results and are saved in a file with the "_observed_results.RDS" extension. When the \code{permutationID} != \code{0}, the results are considered as permutation results and are saved in a file with the -"_permutation_{permutationID}.RDS" extension.} +"_permutation_permutationID.RDS" extension. Where permutationID is the +identifier of the permutation.} \item{type}{One of the \code{"sites"} or \code{"tiles"} strings. Specifies -the type -of differentially methylated elements should be returned. For -retrieving differentially methylated bases \code{type} =\code{"sites"}; for -differentially methylated regions \code{type} = \code{"tiles"}. Default: -\code{"both"}.} +the type of differentially methylated elements should be saved. +Default: \code{"sites"}.} \item{interGenerationResult}{a \code{list} that corresponds to the output of the \code{interGeneration} function, the result of on CpG site or tile analysis on all generations.} - -\item{type}{One of the \code{"sites"} or \code{"tiles"} strings. Specifies -the type of differentially methylated elements should be saved. -Default: \code{"sites"}.} } \value{ \code{0} indicating that all parameters validations have been @@ -44,32 +42,35 @@ successful. \description{ Save the result of on CpG site or tile analysis on all generations. The results are saved in a RDS file. The anaysis can have been -done on the observed or permutated dataset. +done on the observed or shuffled dataset. Each permutation is saved using its identifiant in the file name. } \examples{ ## Load permutation results on sites -permutationResultsFile <- dir(system.file("extdata", -package = "methylInheritance"), pattern = "permutationResultsForSites.RDS", -full.names = TRUE) + +permutationResultsFile <- system.file("extdata", + "permutationResultsForSites.RDS", package="methylInheritance") permutationResults <- readRDS(permutationResultsFile) ## Transform result to GRanges resultsGR <- methylInheritance:::getGRangesFromMethylDiff(methDiff = -permutationResults, pDiff = 10, qvalue = 0.01, type = "hyper") + permutationResults, pDiff = 10, qvalue = 0.01, type = "hyper") ## Extract inter-generationally conserved sites interGenerationResult <- methylInheritance:::interGeneration(resultsGR) +## Create directories +dir.create("TEST", showWarnings = TRUE) +dir.create("TEST/SITES", showWarnings = TRUE) + ## Save results -\dontrun{methylInheritance:::saveInterGenerationResults( -outputDir = "TEST", permutationID=100, type = "sites", -interGenerationResult = interGenerationResult)} +methylInheritance:::saveInterGenerationResults( + outputDir = "TEST/", permutationID=100, type = "sites", + interGenerationResult = interGenerationResult) } \author{ Astrid Deschenes, Pascal Belleau } \keyword{internal} - diff --git a/man/validateExtractInfo.Rd b/man/validateExtractInfo.Rd index f7d8501..613182e 100644 --- a/man/validateExtractInfo.Rd +++ b/man/validateExtractInfo.Rd @@ -9,8 +9,7 @@ validateExtractInfo(allResults, type, inter, position) } \arguments{ \item{allResults}{a \code{list} as created by the -\code{runPermutationUsingMethylKitInfo}, the -\code{runPermutationUsingRDSFile} or the \code{loadAllRDSResults} functions.} +\code{runPermutation} or the \code{loadAllRDSResults} functions.} \item{type}{One of the \code{"sites"} or \code{"tiles"} strings. Specifies the type @@ -43,17 +42,16 @@ data(methylInheritanceResults) ## The function returns 0 when all paramaters are valid methylInheritance:::validateExtractInfo( -allResults = methylInheritanceResults, type = "sites", -inter = "i2", 2) + allResults = methylInheritanceResults, type = "sites", + inter = "i2", 2) ## The function raises an error when at least one paramater is not valid \dontrun{methylInheritance:::validateExtractInfo( -allResults = methylInheritanceResults, type = "sites", -inter = "i2", 12)} + allResults = methylInheritanceResults, type = "sites", + inter = "i2", 12)} } \author{ Astrid Deschenes } \keyword{internal} - diff --git a/man/validateLoadConvergenceData.Rd b/man/validateLoadConvergenceData.Rd new file mode 100644 index 0000000..8f1f944 --- /dev/null +++ b/man/validateLoadConvergenceData.Rd @@ -0,0 +1,56 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/methylInheritanceInternalMethods.R +\name{validateLoadConvergenceData} +\alias{validateLoadConvergenceData} +\title{Validation of some parameters of the +\code{\link{loadConvergenceData}} function} +\usage{ +validateLoadConvergenceData( + analysisResultsDir, + permutationResultsDir, + position, + by +) +} +\arguments{ +\item{analysisResultsDir}{a \code{character} string, the path to the +directory that contains the analysis results. The path can be the same as +for the \code{permutatioNResultsDir} parameter.} + +\item{permutationResultsDir}{a \code{character} string, the path to the +directory that contains the permutation results. The path can be the same +as for the \code{analysisResultsDir} parameter.} + +\item{position}{a positive \code{integer}, the position in the \code{list} +where the information will be extracted.} + +\item{by}{a \code{integer}, the increment of the number of permutations +where the significant level is tested. Default: 100.} +} +\value{ +\code{0} indicating that all parameters validations have been +successful. +} +\description{ +Validation of some parameters needed by the public +\code{\link{loadConvergenceData}} function. +} +\examples{ + +## Get the name of the directory where files are stored +filesDir <- system.file("extdata", "TEST", package="methylInheritance") + +## Merge permutation and observation results +methylInheritance:::validateLoadConvergenceData(analysisResultsDir = + filesDir, permutationResults = filesDir, position = 1, by = 1) + +## The function raises an error when at least one paramater is not valid +\dontrun{methylInheritance:::validateLoadConvergenceData( + analysisResultsDir = filesDir, permutationResults = filesDir, + position = "hello", by = 1))} + +} +\author{ +Astrid Deschenes, Pascal Belleau +} +\keyword{internal} diff --git a/man/validateMergePermutationAndObservation.Rd b/man/validateMergePermutationAndObservation.Rd index 8a477de..3ac5e94 100644 --- a/man/validateMergePermutationAndObservation.Rd +++ b/man/validateMergePermutationAndObservation.Rd @@ -8,16 +8,16 @@ validateMergePermutationAndObservation(permutationResults, observationResults) } \arguments{ -\item{observationResults}{a \code{list} with 1 entry called -\code{OBSERVATION}. The \code{OBSERVATION} entry is a \code{list} containing -the result obtained -with the observed dataset (not permutated).} - -\item{@param}{permutationResults a \code{list} with 1 entry called +\item{permutationResults}{a \code{list} with 1 entry called \code{PERMUTATION}. The \code{PERMUTATION} entry is a \code{list} with a number of entries corresponding to the number of permutations that have been processed. Each entry contains the result of one permutation.} + +\item{observationResults}{a \code{list} with 1 entry called +\code{OBSERVATION}. The \code{OBSERVATION} entry is a \code{list} containing +the result obtained +with the observed dataset (not shuffled).} } \value{ \code{0} indicating that all parameters validations have been @@ -34,9 +34,9 @@ observed <- list() observed[["OBSERVATION"]] <- list() observed[["OBSERVATION"]][["SITES"]] <- list() observed[["OBSERVATION"]][["SITES"]][["i2"]] <- list(HYPER = list(11, 10), -HYPO = list(13, 12)) + HYPO = list(13, 12)) observed[["OBSERVATION"]][["SITES"]][["iAll"]] <- list(HYPER = list(1), -HYPO = list(3)) + HYPO = list(3)) ## Create a permutation result containing only 1 permutation result ## Real perumtations results would have more entries @@ -45,21 +45,20 @@ permutated[["PERMUTATION"]] <- list() permutated[["PERMUTATION"]][[1]] <- list() permutated[["PERMUTATION"]][[1]][["SITES"]] <- list() permutated[["PERMUTATION"]][[1]][["SITES"]][["i2"]] <- list(HYPER = -list(11, 12), HYPO = list(8, 11)) + list(11, 12), HYPO = list(8, 11)) permutated[["PERMUTATION"]][[1]][["SITES"]][["iAll"]] <- list(HYPER = -list(0), HYPO = list(1)) + list(0), HYPO = list(1)) ## Merge permutation and observation results methylInheritance:::validateMergePermutationAndObservation( -permutationResults = permutated, observationResults = observed) + permutationResults = permutated, observationResults = observed) ## The function raises an error when at least one paramater is not valid \dontrun{methylInheritance:::validateMergePermutationAndObservation( -permutationResults = permutated, observationResults = NULL)} + permutationResults = permutated, observationResults = NULL)} } \author{ Astrid Deschenes } \keyword{internal} - diff --git a/man/validateRunObservationUsingMethylKitInfo.Rd b/man/validateRunObservation.Rd similarity index 61% rename from man/validateRunObservationUsingMethylKitInfo.Rd rename to man/validateRunObservation.Rd index 612b5f8..c396cab 100644 --- a/man/validateRunObservationUsingMethylKitInfo.Rd +++ b/man/validateRunObservation.Rd @@ -1,21 +1,37 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/methylInheritanceInternalMethods.R -\name{validateRunObservationUsingMethylKitInfo} -\alias{validateRunObservationUsingMethylKitInfo} +\name{validateRunObservation} +\alias{validateRunObservation} \title{Validation of some parameters of the -\code{\link{runObservationUsingMethylKitInfo}} function} +\code{\link{runObservation}} function} \usage{ -validateRunObservationUsingMethylKitInfo(methylKitInfo, type, outputDir, - nbrCores, nbrCoresDiffMeth, minReads, minMethDiff, qvalue, maxPercReads, - destrand, minCovBasesForTiles, tileSize, stepSize, vSeed) +validateRunObservation( + methylKitData, + type, + outputDir, + nbrCoresDiffMeth, + minReads, + minMethDiff, + qvalue, + maxPercReads, + destrand, + minCovBasesForTiles, + tileSize, + stepSize, + vSeed, + restartCalculation, + saveInfoByGeneration +) } \arguments{ -\item{methylKitInfo}{a \code{list} of \code{methylRawList} entries. Each +\item{methylKitData}{a \code{list} of \code{methylRawList} entries or the +name of the RDS file containing the list. Each \code{methylRawList} contains all the \code{methylRaw} entries related to -one generation. The number of generations must correspond to the number -of entries in the \code{methylKitInfo}. At least 2 generations -must be present to do a permutation analysis. More information can be found -in the Bioconductor methylKit package.} +one generation (first entry = first generation, second entry = second +generation, etc..). The number of generations must correspond to the number +of entries in the \code{methylKitData}. At least 2 generations +must be present to calculate the conserved elements. More information can +be found in the methylKit package.} \item{type}{One of the "sites","tiles" or "both" strings. Specifies the type of differentially methylated elements should be returned. For @@ -26,9 +42,6 @@ differentially methylated regions type="tiles". Default: "both".} the results of the permutation. If the directory does not exist, it will be created.} -\item{nbrCores}{a positive \code{integer}, the number of cores to use when -processing the analysis.} - \item{nbrCoresDiffMeth}{a positive \code{integer}, the number of cores to use for parallel differential methylation calculations.Parameter used for both sites and tiles analysis. The parameter @@ -79,6 +92,16 @@ used when \code{doingTiles} = \code{TRUE}.} \item{vSeed}{a \code{integer}, a seed used when reproducible results are needed. When a value inferior or equal to zero is given, a random integer is used.} + +\item{restartCalculation}{a \code{logical}, when \code{TRUE}, only +permutations that don't have an associated RDS result file are run. Useful +to restart a permutation analysis that has been interrupted.} + +\item{saveInfoByGeneration}{a \code{logical}, when \code{TRUE}, the +information about differentially methylated sites and tiles for each +generation is saved in a RDS file. The information is saved in a different +file for each permutation. The files are only saved when the +\code{outputDir} is not \code{NULL}.} } \value{ \code{0} indicating that all parameters validations have been @@ -86,7 +109,7 @@ successful. } \description{ Validation of some parameters needed by the public -\code{\link{runObservationUsingMethylKitInfo}} function. +\code{\link{runObservation}} function. } \examples{ @@ -94,24 +117,25 @@ Validation of some parameters needed by the public data(samplesForTransgenerationalAnalysis) ## The function returns 0 when all paramaters are valid -methylInheritance:::validateRunObservationUsingMethylKitInfo( -methylKitInfo = samplesForTransgenerationalAnalysis, type = "sites", -outputDir = NULL, nbrCores = 1, -nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 25, qvalue = 0.01, -maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, -tileSize = 1000, stepSize = 500, vSeed = 12) +methylInheritance:::validateRunObservation( + methylKitData = samplesForTransgenerationalAnalysis, type = "sites", + outputDir = "test", nbrCoresDiffMeth = 1, minReads = 10, + minMethDiff = 25, qvalue = 0.01, + maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, + tileSize = 1000, stepSize = 500, vSeed = 12, restartCalculation = TRUE, + saveInfoByGeneration = FALSE) ## The function raises an error when at least one paramater is not valid -\dontrun{methylInheritance:::validateRunObservationUsingMethylKitInfo( -methylKitInfo = samplesForTransgenerationalAnalysis, -type = "tiles", outputDir = NULL, nbrCores = 1, -nbrCoresDiffMeth = 1, minReads = "HI", minMethDiff = 25, qvalue = 0.01, -maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, -tileSize = 1000, stepSize = 500, vSeed = 12)} +\dontrun{methylInheritance:::validateRunObservation( + methylKitData = samplesForTransgenerationalAnalysis, + type = "tiles", outputDir = "test_02", nbrCoresDiffMeth = 1, + minReads = "HI", minMethDiff = 25, qvalue = 0.01, + maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, + tileSize = 1000, stepSize = 500, vSeed = 12, restartCalculation = FALSE, + saveInfoByGeneration = FALSE)} } \author{ Astrid Deschenes } \keyword{internal} - diff --git a/man/validateRunPermutationUsingMethylKitInfo.Rd b/man/validateRunPermutation.Rd similarity index 61% rename from man/validateRunPermutationUsingMethylKitInfo.Rd rename to man/validateRunPermutation.Rd index 9245851..a1c5ea9 100644 --- a/man/validateRunPermutationUsingMethylKitInfo.Rd +++ b/man/validateRunPermutation.Rd @@ -1,22 +1,40 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/methylInheritanceInternalMethods.R -\name{validateRunPermutationUsingMethylKitInfo} -\alias{validateRunPermutationUsingMethylKitInfo} -\title{Parameters validation for the -\code{\link{runPermutationUsingMethylKitInfo}} function} +\name{validateRunPermutation} +\alias{validateRunPermutation} +\title{Parameters validation for the \code{\link{runPermutation}} function} \usage{ -validateRunPermutationUsingMethylKitInfo(methylKitInfo, type, outputDir, - runObservedAnalysis, nbrPermutations, nbrCores, nbrCoresDiffMeth, minReads, - minMethDiff, qvalue, maxPercReads, destrand, minCovBasesForTiles, tileSize, - stepSize, vSeed) +validateRunPermutation( + methylKitData, + type, + outputDir, + runObservedAnalysis, + nbrPermutations, + nbrCores, + nbrCoresDiffMeth, + minReads, + minMethDiff, + qvalue, + maxPercReads, + destrand, + minCovBasesForTiles, + tileSize, + stepSize, + vSeed, + restartCalculation, + saveInfoByGeneration +) } \arguments{ -\item{methylKitInfo}{a \code{list} of \code{methylRawList} entries. Each -\code{methylRawList} contains all the \code{methylRaw} entries related to -one generation. The number of generations must correspond to the number -of entries in the \code{methylKitInfo}.At least 2 generations +\item{methylKitData}{a \code{list} of \code{methylRawList} entries or the +name of the RDS file containing the \code{list}. Each +\code{methylRawList} entry must contain all the \code{methylRaw} entries +related to one generation (first entry = first generation, second +entry = second generation, etc..). The number of generations must +correspond to the number +of entries in the \code{methylKitData}. At least 2 generations must be present to do a permutation analysis. More information can be found -in the Bioconductor methylKit package.} +in the methylKit package.} \item{type}{One of the "sites","tiles" or "both" strings. Specifies the type of differentially methylated elements should be returned. For @@ -86,6 +104,16 @@ used when \code{doingTiles} = \code{TRUE}.} \item{vSeed}{a \code{integer}, a seed used when reproducible results are needed. When a value inferior or equal to zero is given, a random integer is used.} + +\item{restartCalculation}{a \code{logical}, when \code{TRUE}, only +permutations that don't have an associated RDS result file are run. Useful +to restart a permutation analysis that has been interrupted.} + +\item{saveInfoByGeneration}{a \code{logical}, when \code{TRUE}, the +information about differentially methylated sites and tiles for each +generation is saved in a RDS file. The information is saved in a different +file for each permutation. The files are only saved when the +\code{outputDir} is not \code{NULL}.} } \value{ \code{0} indicating that all parameters validations have been @@ -93,7 +121,7 @@ successful. } \description{ Validation of all parameters needed by the public -\code{\link{runPermutationUsingMethylKitInfo}} function. +\code{\link{runPermutation}} function. } \examples{ @@ -101,25 +129,26 @@ Validation of all parameters needed by the public data(samplesForTransgenerationalAnalysis) ## The function returns 0 when all paramaters are valid -methylInheritance:::validateRunPermutationUsingMethylKitInfo( -methylKitInfo = samplesForTransgenerationalAnalysis, type = "sites", -outputDir = NULL, runObservedAnalysis = TRUE, -nbrPermutations = 10000, nbrCores = 1, -nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 25, qvalue = 0.01, -maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, -tileSize = 1000, stepSize = 500, vSeed = 12) +methylInheritance:::validateRunPermutation( + methylKitData = samplesForTransgenerationalAnalysis, type = "sites", + outputDir = "test", runObservedAnalysis = TRUE, + nbrPermutations = 10000, nbrCores = 1, + nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 25, qvalue = 0.01, + maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, + tileSize = 1000, stepSize = 500, vSeed = 12, restartCalculation = FALSE, + saveInfoByGeneration = FALSE) ## The function raises an error when at least one paramater is not valid -\dontrun{methylInheritance:::validateRunPermutationUsingMethylKitInfo( -methylKitInfo = "HI",type = "tiles", outputDir = NULL, -runObservedAnalysis = FALSE, nbrPermutations = 10000, nbrCores = 1, -nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 25, qvalue = 0.01, -maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, -tileSize = 1000, stepSize = 500, vSeed = 12)} +\dontrun{methylInheritance:::validateRunPermutation( + methylKitData = "HI", type = "tiles", outputDir = "test", + runObservedAnalysis = FALSE, nbrPermutations = 10000, nbrCores = 1, + nbrCoresDiffMeth = 1, minReads = 10, minMethDiff = 25, qvalue = 0.01, + maxPercReads = 99.9, destrand = TRUE, minCovBasesForTiles = 10, + tileSize = 1000, stepSize = 500, vSeed = 12, restartCalculation = FALSE, + saveInfoByGeneration = FALSE)} } \author{ Astrid Deschenes } \keyword{internal} - diff --git a/vignettes/demo/F1_case_01.txt b/vignettes/demo/F1_case_01.txt new file mode 100644 index 0000000..63fc115 --- /dev/null +++ b/vignettes/demo/F1_case_01.txt @@ -0,0 +1,3 @@ +chrBase chr base strand coverage freqC freqT +21.9764513 21 9764513 R 38 31.58 68.42 +21.9764522 21 9764522 R 21 9.52 90.48 diff --git a/vignettes/demo/F1_control_01.txt b/vignettes/demo/F1_control_01.txt new file mode 100644 index 0000000..777948c --- /dev/null +++ b/vignettes/demo/F1_control_01.txt @@ -0,0 +1,3 @@ +chrBase chr base strand coverage freqC freqT +21.9764513 21 9764513 F 100 88 12 +21.9764542 21 9764542 R 15 13.33 86.67 \ No newline at end of file diff --git a/vignettes/demo/F2_case_01.txt b/vignettes/demo/F2_case_01.txt new file mode 100644 index 0000000..b8ed233 --- /dev/null +++ b/vignettes/demo/F2_case_01.txt @@ -0,0 +1,3 @@ +chrBase chr base strand coverage freqC freqT +21.9764513 21 9764513 F 33 36.36 63.64 +21.9764533 21 9764533 R 23 4.35 95.65 diff --git a/vignettes/demo/F2_control_01.txt b/vignettes/demo/F2_control_01.txt new file mode 100644 index 0000000..a9a82a2 --- /dev/null +++ b/vignettes/demo/F2_control_01.txt @@ -0,0 +1,3 @@ +chrBase chr base strand coverage freqC freqT +21.9764514 21 9764514 F 40 0 100 +21.9764522 21 9764522 F 30 6.67 93.33 diff --git a/vignettes/demo_01/SITES/SITES_observed_results.RDS b/vignettes/demo_01/SITES/SITES_observed_results.RDS new file mode 100644 index 0000000..f023c7b Binary files /dev/null and b/vignettes/demo_01/SITES/SITES_observed_results.RDS differ diff --git a/vignettes/demo_02/SITES/SITES_permutation_1.RDS b/vignettes/demo_02/SITES/SITES_permutation_1.RDS new file mode 100644 index 0000000..509cfa9 Binary files /dev/null and b/vignettes/demo_02/SITES/SITES_permutation_1.RDS differ diff --git a/vignettes/demo_02/SITES/SITES_permutation_2.RDS b/vignettes/demo_02/SITES/SITES_permutation_2.RDS new file mode 100644 index 0000000..3c277a5 Binary files /dev/null and b/vignettes/demo_02/SITES/SITES_permutation_2.RDS differ diff --git a/vignettes/methylInheritance.Rmd b/vignettes/methylInheritance.Rmd index 7efbd29..0ef3e93 100644 --- a/vignettes/methylInheritance.Rmd +++ b/vignettes/methylInheritance.Rmd @@ -1,12 +1,12 @@ --- -title: "Conserved Differentially Methylated Elements from One Generation to the Next: Inheritance versus Randomness" +title: "Inferring inheritance of differentially methylated changes across multiple generations" author: Astrid Deschênes, Pascal Belleau and Arnaud Droit output: BiocStyle::html_document: toc: true bibliography: biblio.bibtex vignette: > - %\VignetteIndexEntry{Permutation-Based Analysis associating Conserved Differentially Methylated Elements from One Generation to the Next to a Treatment Effect} + %\VignetteIndexEntry{Permutation-Based Analysis associating Conserved Differentially Methylated Elements Across Multiple Generations to a Treatment Effect} %\VignettePackage{methylInheritance} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} @@ -15,6 +15,7 @@ vignette: > ```{r style, echo = FALSE, results = 'asis', warning=FALSE, message=FALSE} BiocStyle::markdown() library(knitr) +library(methylKit) ```
@@ -27,12 +28,19 @@ library(knitr) # Licensing -The `r Rpackage("methylInheritance")` package and the underlying -`r Rpackage("methylInheritance")` code +The `r Biocpkg("methylInheritance")` package and the underlying +`r Biocpkg("methylInheritance")` code are distributed under the Artistic license 2.0. You are free to use and redistribute this software. +# Citing + +If you use this package for a publication, we would ask you to cite the +following: + +> Pascal Belleau, Astrid Deschênes, Marie-Pier Scott-Boyer, Romain Lambrot, Mathieu Dalvai, Sarah Kimmins, Janice Bailey, Arnaud Droit; Inferring and modeling inheritance of differentially methylated changes across multiple generations, Nucleic Acids Research, Volume 46, Issue 14, 21 August 2018, Pages e85. DOI: https://doi.org/10.1093/nar/gky362 + # Introduction DNA methylation plays an important role in the biology of tissue development @@ -53,14 +61,14 @@ a relation between the number of conserved DME from one generation to the next to the inheritance effect of treatment and to dismiss stochastic effect. It is used as a robust alternative to inference based on parametric assumptions. -The `r Rpackage("methylInheritance")` package can perform a permutation +The `r Biocpkg("methylInheritance")` package can perform a permutation analysis on both differentially methylated sites (DMS) and differentially -methylated tiles (DMT) using `r Biocpkg("methylKit")` package. +methylated tiles (DMT) using the `r Biocpkg("methylKit")` package. # Loading methylInheritance package -As with any R package, the `r Rpackage("methylInheritance")` package should +As with any R package, the `r Biocpkg("methylInheritance")` package should first be loaded with the following command: ```{r loadingPackage, warning=FALSE, message=FALSE} @@ -72,8 +80,8 @@ library(methylInheritance) The permutation analysis is a statistical significance test in which the distribution of the test statistic under the null hypothesis is obtained -by calculating the values of the test statistic under rearrangements of -the labels on the observed data points. The rearrangements of the labels is +by calculating the values of the test statistic under rearrangement of +the labels on the observed data points. The rearrangement of the labels is done through repeated random sampling [@Legendre1998, pp. 142-157]. **Null Hypothesis**: The number of conserved DME correspond to a number that @@ -85,21 +93,22 @@ number that can be obtained through a randomness analysis. A typical **methylInheritance** analysis consists of the following steps: 1. Process to a differentially methylation analysis on each generation -separatly using real dataset with `r Rpackage("methylKit")`. +separately using real dataset with the `r Biocpkg("methylKit")` package. 2. Calculate the number of conserved differentially methylated elements between two consecutive generations (F1 and F2, F2 and F3, etc..). The number of conserved differentially methylated elements is also calculated for three -or more consercutive generations, always starting with the first generation +or more consecutive generations, always starting with the first generation (F1 and F2 and F3, F1 and F2 and F3 and F4, etc..). Those results are considered the reference values. 3. Fix a threshold (conventionally 0.05) that is used as a cutoff between the null and alternative hypothesis. -4. Process to a differentially methylation analysis on each permutated dataset. -Each generation is analysed separatly using `r Rpackage("methylKit")` package. +4. Process to a differential methylation analysis on each shuffled dataset. +Each generation is analysed separately using the `r Biocpkg("methylKit")` +package. 5. Calculate the significant level for each consecutive subset of generations. The significant level is defined as the percentage of results equal or higher than the reference values. The reference values are added to the analysis so -that it becomes impossible for the test to conclude that no value are +that it becomes impossible for the test to conclude that no value is as extreme as, or more extreme than the reference values. All those steps have been encoded in the @@ -111,7 +120,7 @@ All those steps have been encoded in the A dataset containing methylation data (6 cases and 6 controls) over three generations has been generated using the -`r Rpackage("methylInheritanceSim")` package. +`r Rpackage("methInheritSim")` package. ```{r caseStudy01, warning=FALSE, message=FALSE, collapse=TRUE} ## Load dataset containing information over three generations @@ -128,41 +137,37 @@ length(demoForTransgenerationalAnalysis) ## The methylRawList object contains two Slots: ## 1- treatment: a numeric vector denoting controls and cases. ## 2- .Data: a list of methylRaw objects. Each object stores the raw -## mehylation data of one sample. +## mehylation data of one sample. ## A section of the methylRaw object containing the information of the ## first sample from the second generation head(demoForTransgenerationalAnalysis[[2]][[1]]) -## The same information could also be obtained using the .Data slot -## head(demoForTransgenerationalAnalysis[[2]]@.Data[[1]]) - ## The treatment vector for each generation ## The number of treatments and controls is the same in each generation ## However, it could also be different. -slot(demoForTransgenerationalAnalysis[[1]], "treatment") -slot(demoForTransgenerationalAnalysis[[2]], "treatment") -slot(demoForTransgenerationalAnalysis[[3]], "treatment") +## Beware that getTreatment() is a function from the methylKit package. +getTreatment(demoForTransgenerationalAnalysis[[1]]) +getTreatment(demoForTransgenerationalAnalysis[[2]]) +getTreatment(demoForTransgenerationalAnalysis[[3]]) ``` ## Observation analysis The observation analysis can be run on all generations using the -*runObservationUsingMehtylKitInfo()* function. +*runObservation()* function. -The observation results can optionally be stored in a RDS file. To store the -results into a RDS file, the *outputDir* parameter must be given a directory -path. +The observation results are stored in a RDS file. The *outputDir* parameter +must be given a directory path. ```{r caseStudy02, warning=FALSE, message=FALSE, collapse=TRUE, cache=TRUE} ## The observation analysis is only done on differentially methylated sites -observationResult <- runObservationUsingMethylKitInfo(methylKitInfo = - demoForTransgenerationalAnalysis, +runObservation(methylKitData = demoForTransgenerationalAnalysis, type = "sites", # Only sites - outputDir = NULL, # RDS files only created when a - # path is given + outputDir = "demo_01", # RDS result files are saved + # in the directory nbrCores = 1, # Number of cores used minReads = 10, # Minimum read coverage minMethDiff = 10, # Minimum difference in methylation @@ -170,36 +175,40 @@ observationResult <- runObservationUsingMethylKitInfo(methylKitInfo = qvalue = 0.01, vSeed = 2101) # Ensure reproducible results -## Only one entry, containing all results, is created for the sites -observationResult$OBSERVATION$SITES +## The results can be retrived using loadAllRDSResults() method +observedResults <- loadAllRDSResults( + analysisResultsDir = "demo_01/", # Directory containing + # the observation + # results + permutationResultsDir = NULL, + doingSites = TRUE, + doingTiles = FALSE) + +observedResults ``` ## Permutation analysis The permutation analysis can be run on all generations using the -*runPermutationUsingMehtylKitInfo()* function. +*runPermutation()* function. The observation and the permutation analysis can be run together by setting the *runObservationAnalysis = TRUE* in the -*runPermutationUsingMehtylKitInfo()* function. +*runPermutation()* function. -All permutations can also be, optionally, saved in RDS files. To store the -results into RDS files, the *outputDir* parameter must be given a directory -path. +All permutations are saved in RDS files. The *outputDir* parameter +must be given a directory path. -At last, the *runPermutationUsingRDSFile()* function also executes a -permutation analysis but instead of passing a methylKit object to it, the -path to a RDS file that contains the methylKit object must be used. +At last, the name of the RDS file that contains the methylKit object can also +be used as an argument to the *runPermutation()* function. ```{r caseStudy03, warning=FALSE, message=FALSE, collapse=TRUE, cache=TRUE} - ## The permutation analysis is only done on differentially methylated sites -permutationResult <- runPermutationUsingMethylKitInfo(methylKitInfo = - demoForTransgenerationalAnalysis, +runPermutation(methylKitData = demoForTransgenerationalAnalysis, # multi-generational dataset type = "sites", # Only sites - outputDir = NULL, # RDS files only created when a - # path is given + outputDir = "demo_02", # RDS permutation files are + # saved in the directory runObservationAnalysis = FALSE, nbrCores = 1, # Number of cores used nbrPermutations = 2, # Should be much higher for a @@ -210,13 +219,16 @@ permutationResult <- runPermutationUsingMethylKitInfo(methylKitInfo = qvalue = 0.01, vSeed = 2101) # Ensure reproducible results -## The length of the PERMUTATION entry should correspond to the number -## of permutations -length(permutationResult$PERMUTATION) +## The results can be retrived using loadAllRDSResults() method +permutationResults <- loadAllRDSResults( + analysisResultsDir = NULL, + permutationResultsDir = "demo_02", # Directory containing + # the permutation + # results + doingSites = TRUE, + doingTiles = FALSE) -## Each entry in PERMUTATION correspond to the result of one permutation -## THe results of the second permutation -permutationResult$PERMUTATION[[2]]$SITES +permutationResults ``` @@ -228,27 +240,26 @@ The observation and permutation results can be merged using the ```{r caseStudy04, warning=FALSE, message=FALSE, collapse=TRUE, cache=TRUE} ## Merge observation and permutation results allResults <- mergePermutationAndObservation(permutationResults = - permutationResult, - observationResults = observationResult) + permutationResults, + observationResults = observedResults) allResults ``` ```{r remove01, warning=FALSE, message=FALSE, echo=FALSE, cache=FALSE} -rm(permutationResult) -rm(observationResult) +rm(permutationResults) +rm(observedResults) ``` When observation and permutation analysis have been run together using the -*runPermutationUsingMehtylKitInfo()* function, this step can be skipped. +*runPermutation()* function, this step can be skipped. ## Extract a specific analysis -The *runPermutationUsingMehtylKitInfo()* and -*runObservationUsingMehtylKitInfo()* functions +The *runPermutation()* and *runObservation()* functions calculate the number of conserved differentially methylated elements -between two consecutive generations (F1 and F2, F2 and F3, etc..). They also -calculate the number of conserved differentially methylated elements is also +between two consecutive generations (F1 and F2, F2 and F3, etc..). The +number of conserved differentially methylated elements is also calculated for three or more consecutive generations, always starting with the first generation (F1 and F2 and F3, F1 and F2 and F3 and F4, etc..). @@ -268,13 +279,14 @@ F3, etc..) F1 and F2 and F3 and F4, etc..) ```{r caseStudy05, warning=FALSE, message=FALSE, collapse=TRUE, cache=FALSE} -## Differentially conserved sites between F1 and F2 generations +## Conserved differentially methylated sites between F1 and F2 generations F1_and_F2_results <- extractInfo(allResults = allResults, type = "sites", inter = "i2", position = 1) head(F1_and_F2_results) ``` + ## Significant level and visual representation The permutation analysis has been run on the *demoForTransgenerationalAnalysis* @@ -283,10 +295,10 @@ those permutations will be used to generate the significant levels and the visual representations. ```{r caseStudyLoad, warning=FALSE, message=FALSE, cache=TRUE, echo = FALSE, cache=TRUE} -demoResults <- readRDS(dir(system.file("extdata", - package = "methylInheritance"), - pattern = "resultsForTransgenerationalAnalysis.RDS", - full.names = TRUE)) +demoFile <- system.file("extdata", "resultsForTransgenerationalAnalysis.RDS", + package="methylInheritance") + +demoResults <- readRDS(demoFile) ``` ```{r caseStudy06, warning=FALSE, message=FALSE, collapse=TRUE, cache=TRUE} @@ -307,6 +319,180 @@ F2_and_F3 <- extractInfo(allResults = demoResults, type = "sites", output <- plotGraph(F1_and_F2) ``` + +# Possibility to restart a permutation analysis + +When a large number of permutations is processed, the time needed to +process them all may be long (especially when the number of available CPU is +limited). Furthermore, some permutations can fail due to parallelization +problems. + +The **methylInheritance** package offers the possibility to restart +an analysis and run only missing permutation results. To take advantage of this +option, the *outputDir* parameter must not be *NULL* so that permutation +results are saved in RDS files. When the *restartCalculation* is set to *TRUE*, +the method will load the permutation results present in RDS files (when +available) and only rerun permutations that don't have an associated RDS file. + + +```{r restartAnalysis, warning=FALSE, message=FALSE, collapse=TRUE, cache=TRUE} +## The permutation analysis is only done on differentially methylated tiles +## The "output" directory must be specified +## The "vSeed" must be specified to ensure reproducible results +## The "restartCalculation" is not important the first time the analysis is run +permutationResult <- runPermutation( + methylKitData = demoForTransgenerationalAnalysis, # multi-generational dataset + type = "tiles", # Only tiles + outputDir = "test_restart", # RDS files are created + runObservationAnalysis = TRUE, + nbrCores = 1, # Number of cores used + nbrPermutations = 2, # Should be much higher for a + # real analysis + vSeed = 212201, # Ensure reproducible results + restartCalculation = FALSE) + +## Assume that the process was stopped before it has done all the permutations + +## The process can be restarted +## All parameters must be identical to the first analysis except "restartCalculation" +## The "restartCalculation" must be set to TRUE +permutationResult <- runPermutation( + methylKitData = demoForTransgenerationalAnalysis, # multi-generational dataset + type = "tiles", # Only tiles + outputDir = "test_restart", # RDS files are created + runObservationAnalysis = TRUE, + nbrCores = 1, # Number of cores used + nbrPermutations = 2, # Should be much higher for a + # real analysis + vSeed = 212201, # Ensure reproducible results + restartCalculation = TRUE) +``` + + +# Format multigenerational dataset into an input + +The permutation analysis needs a *list* of *methylRawList* objects +as input. A *methylRawList* is a *list* of *methylRaw* objects. +The *methylRawList* and *methylRaw* objects are defined in the +`r Biocpkg("methylKit")` package. + +To create a *methylRawList*, all samples (cases and controls) from the same +generation must be first separately transformed into a *methylRaw* object. +The S4 *methylRaw* class extends *data.frame* class and has been created to +store raw methylation data. The raw methylation is essentially percent +methylation values and read coverage values per base or region. + +Excluding the *data.frame* section, the slots present in the *methylRaw* +class are: + +* sample.id: a string, the sample identification +* assembly: a string, the genomic assembly +* context: a string, the methylation context, as an exemple, CpG, CpH, etc... +* resolution: a string, the resolution of methylation information, +mainly 'base' or 'region' + +```{r demoRaw1, warning=FALSE, message=FALSE, collapse=TRUE, cache=TRUE} +## The list of methylRaw objects for all controls and cases related to F1 +f1_list <- list() +f1_list[[1]] <- new("methylRaw", + data.frame(chr = c("chr21", "chr21"), + start = c(9764513, 9764542), + end = c(9764513, 9764542), strand = c("+", "-"), + coverage = c(100, 15), numCs = c(88, 2), + numTs = c(100, 15) - c(88, 2)), + sample.id = "F1_control_01", assembly = "hg19", + context = "CpG", resolution = 'base') +f1_list[[2]] <- new("methylRaw", + data.frame(chr = c("chr21", "chr21"), + start = c(9764513, 9764522), + end = c(9764513, 9764522), strand = c("-", "-"), + coverage = c(38, 21), numCs = c(12, 2), + numTs = c(38, 21) - c(12, 2)), + sample.id = "F1_case_02", assembly = "hg19", + context = "CpG", resolution = 'base') + +## The list of methylRaw objects for all controls and cases related to F2 +f2_list <- list() +f2_list[[1]] <- new("methylRaw", + data.frame(chr = c("chr21", "chr21"), + start = c(9764514, 9764522), + end = c(9764514, 9764522), strand = c("+", "+"), + coverage = c(40, 30), numCs = c(0, 2), + numTs = c(40, 30) - c(0, 2)), + sample.id = "F2_control_01", assembly = "hg19", + context = "CpG", resolution = 'base') +f2_list[[2]] <- new("methylRaw", + data.frame(chr = c("chr21", "chr21"), + start = c(9764513, 9764533), + end = c(9764513, 9764533), strand = c("+", "-"), + coverage = c(33, 23), numCs = c(12, 1), + numTs = c(33, 23) - c(12, 1)), + sample.id = "F2_case_01", assembly = "hg19", + context = "CpG", resolution = 'base') + +## The list to use as input for methylInheritance +final_list <- list() + +## The methylRawList for F1 - the first generation is on the first position +final_list[[1]] <- new("methylRawList", f1_list, treatment = c(0,1)) +## The methylRawList for F2 - the second generation is on the second position +final_list[[2]] <- new("methylRawList", f2_list, treatment = c(0,1)) + +## A list of methylRawList ready for methylInheritance +final_list +``` + +Another approach is to transform the files that contain the raw methylation +information into a format that can be read by the `r Biocpkg("methylKit")` +*methRead* function. The *methRead* function implements methods that enable +the creation of *methylRawList* objects. + +Here is one valid file format among many (tab separated): +``` +chrBase chr base strand coverage freqC freqT +1.176367 1 176367 R 29 100.00 0.00 +1.176392 1 176392 R 58 100.00 0.00 +1.176422 1 176422 R 29 3.45 96.55 +1.176552 1 176552 R 58 96.55 3.45 +``` + +```{r demoRaw2, warning=FALSE, message=FALSE, collapse=TRUE, cache=TRUE} +library(methylKit) + +## The methylRawList for F1 +generation_01 <- methRead(location = list("demo/F1_control_01.txt", "demo/F1_case_01.txt"), + sample.id = list("F1_control_01", "F1_case_01"), + assembly = "hg19", treatment = c(0, 1), context = "CpG") + +## The methylRawList for F2 +generation_02 <- methRead(location = list("demo/F2_control_01.txt", "demo/F2_case_01.txt"), + sample.id = list("F2_control_01", "F2_case_01"), + assembly = "hg19", treatment = c(0, 1), context = "CpG") + +## A list of methylRawList ready for methylInheritance +final_list <- list(generation_01, generation_02) +final_list +``` + +More information about methRead function can be found in the documentation of +the `r Biocpkg("methylKit")` package. + + +# Acknowledgment + +We thank Marie-Pier Scott-Boyer for her advice on the vignette content. + + +# Session info + +Here is the output of sessionInfo() on the system on which this document +was compiled: + +```{r sessionInfo, echo=FALSE} +sessionInfo() +``` + + # References diff --git a/vignettes/test_restart/TILES/TILES_observed_results.RDS b/vignettes/test_restart/TILES/TILES_observed_results.RDS new file mode 100644 index 0000000..38525ff Binary files /dev/null and b/vignettes/test_restart/TILES/TILES_observed_results.RDS differ diff --git a/vignettes/test_restart/TILES/TILES_permutation_1.RDS b/vignettes/test_restart/TILES/TILES_permutation_1.RDS new file mode 100644 index 0000000..f9e0ba3 Binary files /dev/null and b/vignettes/test_restart/TILES/TILES_permutation_1.RDS differ diff --git a/vignettes/test_restart/TILES/TILES_permutation_2.RDS b/vignettes/test_restart/TILES/TILES_permutation_2.RDS new file mode 100644 index 0000000..4c72608 Binary files /dev/null and b/vignettes/test_restart/TILES/TILES_permutation_2.RDS differ