# RaMWAS Parameters

# Initializing RaMWAS parameters

There are several ways to initialize the parameters for calling RaMWAS pipeline functions. The parameters can be stored in an R list like this:

    param = ramwasParameters(
        dirproject = ".",
        dirbam = "bams",
        filebamlist = "bam_list.txt",
        filecpgset = "Simulated_chromosome.rds",
        cputhreads = 2,
        scoretag = "MAPQ",
        minscore = 4,
        minfragmentsize = 50,
        maxfragmentsize = 250,
        filecovariates = "covariates.txt",
        modelcovariates = NULL,
        modeloutcome = "age",
        modelPCs = 0,
        toppvthreshold = 1e-5,
        cvnfolds = 10,
        mmalpha = 0,
        mmncpgs = c(5, 10, 50, 100, 500, 1000, 5000, 10000)
    )

Alternatively, the parameters can be set in a separate R code file, which is processed into a list as above by `parametersFromFile` function. The R code file can contain lines like this:

    ### R parameter file
    dirbam = "/ramwas_project/bams/"
    dirproject = "/ramwas_project/"
    filebamlist = "/ramwas_project/000_list_of_files.txt"
    scoretag = "AS"
    minscore = 100

    ### platform dependent part
    if(.Platform$OS.type == "windows"){
        filecpgset="C:/RaMWAS/CpG_set/cpgset_hg19_SNPS_at_MAF_0.05.rds"
    } else {
        filecpgset="/computing_cluster/ramwas/cpgset_hg19_SNPS_at_MAF_0.05.rds"
    }

# Explanation of all parameters

## Parameters pointing to directories

The project directory parameter is `dirproject`. Files specified by `file*` parameters are looked for here, unless they have the full path specified. By default `dirproject` is set to the current directory.

The `dirbam` directory is the location where RaMWAS expects to find BAM files. If it is not an absolute path, it is considered to be relative to the `dirproject`.

The `dirfilter` directory is, by default, the same as `dirproject`. All files created by RaMWAS are created within this directory. If the user wants to test different read filtering rules, they can set `dirfilter` to `TRUE`. This will set it to something like “Filter_MAPQ_4”, there “MAPQ” is the BAM field used for filtering and “4” is the threshold.

The `dirrbam` parameter is the location where RaMWAS saves RaMWAS raw data files (read start locations) after scanning BAMs. It is “rds_rbam” by default and is located in `dirfilter`.

The `dirrqc` parameter is the location where RaMWAS saves QC files in R format after scanning BAMs. It is “rds_qc” by default and is located in `dirfilter`.

The `dirqc` parameter is the location where RaMWAS saves QC plots and text files (BAM QC info) after scanning BAMs. It is “qc” by default and is located in `dirfilter`.

The `dircoveragenorm` parameter is the sub-directory where RaMWAS saves coverage matrix at Step 3 of the pipeline. It is “coverage_norm_123” by default (123 is the number of samples) and is located in `dirfilter`.

The `dirtemp` parameter is the directory where RaMWAS stores temporary files during construction of coverage matrix at Step 3 of the pipeline. It is “temp” by default and is located in `dircoveragenorm`. For better performance it can be set to a location on a different hard drive than `dircoveragenorm`.

The `dirpca` parameter is the sub-directory where RaMWAS saves results of PCA analysis at Step 4 of the pipeline. It is “PCA_12_cvrts_0b0a0c” by default (12 is the number of covariates regressed out and 0b0a0c is a unique code to differentiate different sets of 12 covariates) and is located in `dircoveragenorm`.

The `dirmwas` parameter is the sub-directory where RaMWAS saves results of MWAS analysis at Step 5. It is “Testing_age_7_PCs” by default (age is the phenotype being tested and 7 is number of top PCs included in the model) and is located in `dirpca`.

The `dircv` parameter is the sub-directory where RaMWAS saves results of Methylation Risk Score analysis at Step 7. It is “CV_10_folds” by default (10 is number of folds in N-fold cross validation) and is located in `dirmwas`.

## Parameters pointing to files

### BAM names

Parameter `filebamlist`, if defined, must point to a text file with one BAM file name per line. BAM file names can include path, relative to `dirbam` or absolute.

Such file may looks like this.

    batch1/b1sample1.bam
    batch1/b1sample2.bam
    batch2/b2sample1.bam
    batch2/b2sample2.bam
    batch2/b2sample3.bam
    batch4/sample4.bam

This file is then loaded into `bamnames` parameter, with “.bam” extension stripped.

Note: BAM file names must be different. For example, the list of BAMS below is NOT allowed, as it contains “sample1.bam” twice:

    batch1/sample1.bam
    batch1/sample2.bam
    batch2/sample1.bam

### BAM to sample matching

The `filebam2sample` parameter lets RaMWAS know the BAM to sample correspondence. It provides information on how BAMs from the same sample are to be combined. Each line in `filebam2sample` must have information for one sample. If sample1 contains reads from bam1, bam2 and bam3, the line should be

> sample1=bam1,bam2,bam3

If the sample name matches the bam name, the line can simply contain that name

> sample2

The `filebam2sample` file is scanned into `bam2sample` list. The elements of the list are bam names, and their names are sample names. For example:

    bam2sample = list(
        sample1 = c("bam1","bam2","bam3"),
        sample2 = "sample2"
    )

### CpG locations

RaMWAS calculates CpG scores and performs further analyses at a set of CpGs (or locations in general) defined by the user via `filecpgset` parameter. The `filecpgset` parameter must point to an .rds file (a file saved using `saveRDS` function), with the set of locations stored as a `list` with one sorted vector of CpG locations per chromosome.

    cpgset = list(
                chr1 = c(12L, 57L, 123L),
                chr2 = c(45L, 95L, 99L, 111L),
                chr3 = c(22L, 40L, 199L, 211L) )

In practice, the set should depend on the reference genome and can include CpGs created by common SNPs.

Optionally, parameter `filenoncpgset`, can point to a file storing vetted locations away from any CpGs.

For more on CpG sets see the CpG set vignette

### File with covariates

The parameter `filecovariates`, if defined, must point to a file containing phenotype information and covariates for the available samples. If the file has extension “.csv”, it is assumed to be comma separated, otherwise - tab separated. It must have a header and the first column must have sample names as defined by `bam2sample` parameter (see above).

The data in `filecovariates` is read into the `covariates` parameter.

## Multithreading

Many parts of RaMWAS are parallelized. The `cputhreads` parameter determines the maximum number of CPU intensive tasks running in parallel. By default `cputhreads` is set to the number of CPU cores.

Some tasks are disk intensive. The maximum number of such tasks running in parallel is set by the `diskthreads` parameter. By default `diskthreads` value is 2. Higher values can be beneficial on machine with lots of RAM.

On some systems the performance is better if different jobs are prevented from simultaneous access to files. To enforce this for filematrices set `usefilelock=TRUE`.

## Read filtering

The reads are filtered by `scoretag` parameter, which is usually the “MAPQ” field or “AS” tag in the BAM file (BAM file format). The `minscore` parameter defines the minimum admissible score, reads with scores below that are excluded.

If there the are more than `maxrepeats` read with the same start position, this excess is assumed to be the result of template preparation or amplification artifacts and count is reset to `maxrepeaets` (it is set to 3 by default).

## Coverage matrix

The CpGs in CpG set defined by `filecpgset` are filtered based on their coverage.

- A CpG must have average equal or greater than `minavgcpgcoverage` (default is 0.3).
- A CpG must have at least `minnonzerosamples` proportion of samples with nonzero coverage
  (default is 0.3, i.e. a CpG is preserved if at least 30% of samples have non-zero coverage).

The file operations in this step can be performed faster if done in large blocks. To set the block size use `buffersize` parameter. Be default it is set to 1 GB (`buffersize = 1e9`).

Numerical values take 8 bytes is stored with full precision. The coverage matrix does not need such precision and can safely be stored with 4 bytes per value (single precision). The value size is set by `doublesize` parameter, which is 4 by default.

## PCA and MWAS

Both PCA and MWAS correct for variation explained by selected covariates set by `modelcovariates`. The `modelcovariates` parameter must name variables in `filecovariates`/`covariates`.

By default, the tested linear model includes a constant. To exclude it, set `modelhasconstant` parameter to `FALSE`.

MWAS tests for association of normalized CpG coverage with `modeloutcome`, accounting for variation of top `modelPCs` principal components.

MWAS produces a QQ-plot in `dirmwas`. The title of the QQ-plot can be changed by the `qqplottitle` parameter. To exclude the title set `qqplottitle=""`.

Top MWAS results are saved in a text file `Top_tests.txt`. Parameter `toppvthreshold` defines p-value threshold for selection of top results. Alternatively, it can define the number of top results, if it is set to a value larger than 1.

## Annotation of top findings

The annotation is done using `biomaRt`. package.

The parameters include:

- `bihost` – BioMart host site.
  Default is `grch37.ensembl.org`.
- `bimart` – BioMart database name, see listMarts().
  Default is `ENSEMBL_MART_ENSEMBL`.
- `bidataset` – BioMart data set, see listDatasets().
- `biattributes` – are attributes of interest, see listAttributes(). Default is `c("hgnc_symbol","entrezgene","strand")`.
- `bifilters` – lists filters (if any), see listFilters().
- `biflank` – indicates the maximum allowed distance from the CpG to the annotation element.

Here is an example on how to select a custom biomart annotation track:

    library(biomaRt)
    library(ramwas)

    # First pick a host.
    bihost = "grch37.ensembl.org"

    # First we list databases
    listOfMarts = listMarts(host = bihost)
    pander(head(listOfMarts, 10))

    # Pick a database
    bimart = "ENSEMBL_MART_ENSEMBL"

    # Connect to the database
    mart = useMart(biomart = bimart, host = bihost)

    # List the data sets in the database
    listOfDatasets = listDatasets(mart = mart)
    pander(head(listOfDatasets, 10))

    # Pisk a data set
    bidataset = "hsapiens_gene_ensembl"

    # Connect to the data set
    mart = useMart(biomart = bimart, dataset = bidataset, host = bihost)

    # List the attributes
    listOfAttributes = listAttributes(mart)
    pander(head(listOfAttributes, 10))

    # Pick attributes
    biattributes = c("hgnc_symbol", "entrezgene", "strand")

    listOfFilters = listFilters(mart)
    pander(head(listOfFilters, 20))

    # Pick a filter
    bifilters = list(with_hgnc_trans_name=TRUE)

    # Test a location
    chr = "chr1"
    pos =  15975530
    param = ramwasParameters(
        bihost = bihost,
        bimart = bimart,
        bidataset = bidataset,
        biattributes = biattributes,
        bifilters = bifilters,
        biflank = 0)

    anno = ramwasAnnotateLocations(param, chr, pos)
    pander(anno)

## Methylation risk score

RaMWAS predicts the outcome variable (`modeloutcomes` parameter) using top `mmncpgs` CpGs from the MWAS. This prediction is done for each fold in k-fold cross validation and the prediction performance is measured via correlations and (for binary outcomes) ROC curves.

To run the procedure for multiple number of top CpGs, The parameter `mmncpgs` can be set to a vector of multiple values.

The elastic net mixing parameter alpha can be set via `mmalpha` parameter. The number of folds `cvnfolds` in the K-fold cross validation is 10 by default.

The split into folds is random. The random seed can be set with the `randseed` parameter, which is set to `18090212` by default for consistency across runs.

### Choosing the number of folds `cvnfolds` in the cross validation

When selecting the number of folds, K, in K-fold cross validation a researcher faces a trade off. On one hand, larger K allows the training set [of size approximately \(\frac{K-1}{K}N\) to better match the size of the complete data set. On the other hand, the computational complexity of cross validation grows linearly with K. As a balance, \(K = 5\) or \(10\) is often chosen. The most extreme case of \(K = N\) is known as the leave-one-out cross validation procedure.

## Joint analysis with genotype data

The joint analysis of methylation and genotype data is described in the corresponding vignette.

The SNP data must be stored in a filematrix with dimensions matching the CpG score matrix. Its name must be defined by `fileSNPs` parameter, with absolute path or relative to `dircoveragenorm`.

The results of the joint analysis are stored in `dirSNPs` directory. By default, the directory is created within `dircoveragenorm` directory.