mergeBamByFactor {systemPipeR} | R Documentation

## Merge BAM files based on factor

### Description

Merges BAM files based on sample groupings provided by a factor using internally the `mergeBam` function from the `Rsamtools` package. The function also returns an updated `SYSargs` or `SYSargs2` object containing the paths to the merged BAM files as well as to the unmerged BAM files if there are any. All rows of merged parent samples are removed.

The functionality provided by `mergeBamByFactor` is useful for experiments where pooling of replicates is advantageous to maximize the depth of read coverage, such as prior to peak calling in ChIP-Seq or miRNA gene prediction experiments.

### Usage

    mergeBamByFactor(args, mergefactor = "Factor", overwrite = FALSE, silent = FALSE, ...)

### Arguments

`args` | An instance of `SYSargs` or `SYSargs2` constructed from a `targets` file where the first column (`targetsin(args)` or `targets.as.df(targets(args))`) contains the paths to the BAM files along with the column title `FileName`.
`mergefactor` | `factor` containing the grouping information required for merging the BAM files referenced in the first column of `targetsin(args)` or `targets.as.df(targets(args))`. The default uses `Factor` column from the `targets` files as factor. The latter merges BAM files for which replicates are specified in the `Factor` column.
`overwrite` | If `overwrite=FALSE` existing BAM files of the same name will not be overwritten.
`silent` | If `silent=TRUE` print statements will be suppressed.
`...` | To pass on additional arguments to the internally used `mergeBam` function from `Rsamtools`.

### Value

The merged BAM files will be written to output files with the following naming convention: <first_BAM_file_name>_<grouping_label_of_factor>.<bam>. In addition, the function returns an updated `SYSargs` or `SYSargs2` object where all output file paths contain the paths to the merged BAM files. The rows of the merged parent samples are removed and the rows of the unmerged samples remain unchanged.

### Author(s)

Thomas Girke

### See Also

`writeTargetsout`, `writeTargetsRef`

### Examples

    ## Construct initial SYSargs object
    targetspath <- system.file("extdata", "targets_chip.txt", package="systemPipeR")
    parampath <- system.file("extdata", "bowtieSE.param", package="systemPipeR")
    args <- systemArgs(sysma=parampath, mytargets=targetspath)

    ## Not run:
    ## After running alignmets (e.g. with Bowtie2) generate targets file
    ## for the corresponding BAM files. The alignment step is skipped here.
    writeTargetsout(x=args, file="targets_bam.txt", overwrite=TRUE)
    args <- systemArgs(sysma=NULL, mytargets="targets_bam.txt")

    ## Merge BAM files and return updated SYSargs object
    args_merge <- mergeBamByFactor(args, overwrite=TRUE, silent=FALSE)

    ## Export modified targets file
    writeTargetsout(x=args_merge, file="targets_mergeBamByFactor.txt", overwrite=TRUE)

    ## End(Not run)

[Package systemPipeR version 1.21.6 Index]