conform {sparrow} | R Documentation

## (Re)-map geneset IDs to the rows in an expression object.

### Description

`conform`-ing, a `GeneSetDb` to a target expression object is an important step required prior to perform any type of GSEA. This function maps the featureIds used in the GeneSetDb to the elements of a target expression object (ie. the rows of an expression matrix, or the elements of a vector of gene-level statistics).

After `conform`-ation, each geneset in the `GeneSetDb` is flagged as active (or inactive) given the number of its features that are successfully mapped to `target` and the minimum and maximum number of genes per geneset required as specified by the `min.gs.size` and `max.gs.size` parameters, respectively.

Only genesets that are marked with `active = TRUE` will be used in any downstream gene set operations.

### Usage

    conform(x, ...)

    unconform(x, ...)

    ## S4 method for signature 'GeneSetDb'
    conform(
      x,
      target,
      unique.by = c("none", "mean", "var"),
      min.gs.size = 2L,
      max.gs.size = Inf,
      match.tolerance = 0.25,
      ...
    )

    ## S4 method for signature 'GeneSetDb'
    unconform(x, ...)

    is.conformed(x, to)

### Arguments

`x` | The GeneSetDb
`...` | moar args
`target` | The expression object/matrix to conform to. This could also just be a character vector of IDs.
`unique.by` | If there are multiple rows that map to the identifiers used in the genesets, this is a means to pick the single row for that ID
`min.gs.size` | Ensure that the genesets that make their way to the `GeneSetDb@table` are of a minimum size
`max.gs.size` | Ensure that the genesets that make their way to the `GeneSetDb@table` are smaller than this size
`match.tolerance` | Numeric value between [0,1]. If the fraction of `feature_id`s used in `x` that match `rownames(y)` is below this number, a warning will be fired.
`to` | the object to test conformation to

### Value

A `GeneSetDb()` that has been matched/conformed to an expression object target `y`.

### Functions

- `is.conformed`: Checks to see if GeneSetDb `x` is conformed to a target object `to`

### Related Functions

- `unconform()`: Resets the conformation mapping.

- `is.conformed()`: If `to` is missing, looks for evidence that `conform` has been called (at all) on `x`. If `to` is provided, specifically checks that `x` has been conformed to the target object `to`.

### Examples

    es <- exampleExpressionSet()
    gdb <- exampleGeneSetDb()
    head(geneSets(gdb))
    gdb <- conform(gdb, es)
    ## Note the updated values `active` flag, and n (the number of features
    ## mapped per gene set)
    head(geneSets(gdb))

[Package sparrow version 1.0.3 Index]