runPermutation {methylInheritance} | R Documentation

## 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 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.

### 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

`methylKitData` | a `list` of `methylRawList` entries or the name of the RDS file containing the `list`. Each `methylRawList` entry must contain all the `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 `methylKitData`. At least 2 generations must be present to make a permutation analysis. More information can be found in the methylKit package.
`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".
`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: `"output"`.
`runObservationAnalysis` | a `logical`, when `runObservationAnalysis` = `TRUE`, a CpG analysis on the observed dataset is done. Default: `TRUE`.
`nbrPermutations,` | a positive `integer`, the total number of permutations that is going to be done. Default: `1000`.
`nbrCores` | a positive `integer`, the number of cores to use when processing the analysis. Default: `1` and always `1` for Windows.
`nbrCoresDiffMeth` | a positive `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 `num.cores` parameter in the package `methylKit`. Default: `1` and always `1` for Windows.
`minReads` | a positive `integer` Bases and regions having lower coverage than this count are discarded. The parameter corresponds to the `lo.count` parameter in the package `methylKit`.
`minMethDiff` | a positive `double` between [0,100], the absolute value of methylation percentage change between cases and controls. The parameter corresponds to the `difference` parameter in the methylKit package. Default: `10`.
`qvalue` | a positive `double` between [0,1], the cutoff for qvalue of differential methylation statistics. Default: `0.01`.
`maxPercReads` | a `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 `hi.perc` parameter in the package `methylKit`. Default: `99.9`.
`destrand` | a `logical`, when `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: `FALSE`.
`minCovBasesForTiles` | a non-negative `integer`, the minimum number of bases to be covered in a given tiling window. The parameter corresponds to the `cov.bases` parameter in the package `methylKit`. Only used when `doingTiles` = `TRUE`. Default: `0`.
`tileSize` | a positive `integer`, the size of the tiling window. The parameter corresponds to the `win.size` parameter in the package `methylKit`. Only used when `doingTiles` = `TRUE`. Default: `1000`.
`stepSize` | a positive `integer`, the step size of tiling windows. The parameter corresponds to the `stepSize` parameter in the package `methylKit`. Only used when `doingTiles` = `TRUE`. Default: `1000`.
`vSeed` | a `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: `-1`.
`restartCalculation` | a `logical`, when `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.
`saveInfoByGeneration` | a `logical`, when `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 `outputDir` parameter.

### Value

`0`.

### Author(s)

Astrid Deschenes, Pascal Belleau

### See Also

`mergePermutationAndObservation` for detail description, in the Value section, of the `methylInheritanceAllResults` object as well as its `PERMUTATION` section.

### 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)
    }

[Package methylInheritance version 1.8.0 Index]