createPositives {benchdamic} | R Documentation

## createPositives

### Description

Inspect the list of p-values or/and log fold changes from the output of the differential abundance detection methods and count the True Positives (TP) and the False Positives (FP).

### Usage

    createPositives(
      object,
      priorKnowledge,
      enrichmentCol,
      namesCol = NULL,
      slot = "pValMat",
      colName = "adjP",
      type = "pvalue",
      direction = NULL,
      threshold_pvalue = 1,
      threshold_logfc = 0,
      top = NULL,
      alternative = "greater",
      verbose = FALSE,
      TP,
      FP
    )

### Arguments

`object` | Output of differential abundance detection methods. `pValMat`, `statInfo` matrices, and method's `name` must be present (See vignette for detailed information).
`priorKnowledge` | `data.frame` (with feature names as `row.names`) containing feature level metadata.
`enrichmentCol` | name of the column containing information for enrichment analysis.
`namesCol` | name of the column containing new names for features (default `namesCol = NULL`).
`slot` | A character vector with 1 or number-of-methods-times repeats of the slot names where to extract values for each method (default `slot = "pValMat"`).
`colName` | A character vector with 1 or number-of-methods-times repeats of the column name of the slot where to extract values for each method (default `colName = "rawP"`).
`type` | A character vector with 1 or number-of-methods-times repeats of the value type of the column selected where to extract values for each method. Two values are possible: `"pvalue"` or `"logfc"` (default `type = "pvalue"`).
`direction` | A character vector with 1 or number-of-methods-times repeats of the `statInfo`'s column name containing information about the signs of differential abundance (usually log fold changes) for each method (default `direction = NULL`).
`threshold_pvalue` | A single or a numeric vector of thresholds for p-values. If present, features with p-values lower than `threshold_pvalue` are considered differentially abundant. Set `threshold_pvalue = 1` to not filter by p-values.
`threshold_logfc` | A single or a numeric vector of thresholds for log fold changes. If present, features with log fold change absolute values higher than `threshold_logfc` are considered differentially abundant. Set `threshold_logfc = 0` to not filter by log fold change values.
`top` | If not null, the `top` number of features, ordered by p-values or log fold change values, are considered as differentially abundant (default `top = NULL`).
`alternative` | indicates the alternative hypothesis and must be one of `"two.sided"`, `"greater"` or `"less"`. You can specify just the initial letter. Only used in the 2 by 2 case.
`verbose` | Boolean to display the kind of extracted values (default `verbose = FALSE`).
`TP` | A list of length-2 vectors. The entries in the vector are the direction ("UP Abundant", "DOWN Abundant", or "non-DA") in the first position, and the level of the enrichment variable (`enrichmentCol`) which is expected in that direction, in the second position.
`FP` | A list of length-2 vectors. The entries in the vector are the direction ("UP Abundant", "DOWN Abundant", or "non-DA") in the first position, and the level of the enrichment variable (`enrichmentCol`) which is not expected in that direction, in the second position.

### Value

a `data.frame` object which contains the number of TPs and FPs features for each method and for each threshold of the `top` argument.

### See Also

`getPositives`, `plotPositives`.

### Examples

    data("ps_plaque_16S")
    data("microbial_metabolism")

    # Extract genera from the phyloseq tax_table slot
    genera <- phyloseq::tax_table(ps_plaque_16S)[, "GENUS"]
    # Genera as rownames of microbial_metabolism data.frame
    rownames(microbial_metabolism) <- microbial_metabolism$Genus
    # Match OTUs to their metabolism
    priorInfo <- data.frame(genera,
        "Type" =  microbial_metabolism[genera, "Type"])
    # Unmatched genera becomes "Unknown"
    unknown_metabolism <- is.na(priorInfo$Type)
    priorInfo[unknown_metabolism, "Type"] <- "Unknown"
    priorInfo$Type <- factor(priorInfo$Type)
    # Add a more informative names column
    priorInfo[, "newNames"] <- paste0(rownames(priorInfo), priorInfo[, "GENUS"])

    # Add some normalization/scaling factors to the phyloseq object
    my_norm <- setNormalizations(fun = c("norm_edgeR", "norm_CSS"),
        method = c("TMM", "median"))
    ps_plaque_16S <- runNormalizations(normalization_list = my_norm,
        object = ps_plaque_16S)
    # Initialize some limma based methods
    my_limma <- set_limma(design = ~ 1 + HMP_BODY_SUBSITE, coef = 2,
        norm = c("TMM", "CSSmedian"))

    # Perform DA analysis
    Plaque_16S_DA <- runDA(method_list = my_limma, object = ps_plaque_16S)

    # Count TPs and FPs, from the top 1 to the top 20 features.
    # As direction is supplied, features are ordered by "logFC" absolute values.
    positives <- createPositives(object = Plaque_16S_DA,
    priorKnowledge = priorInfo, enrichmentCol = "Type", namesCol = "newNames",
    slot = "pValMat", colName = "rawP", type = "pvalue", direction = "logFC",
    threshold_pvalue = 1, threshold_logfc = 0, top = 1:20,
    alternative = "greater", verbose = FALSE,
    TP = list(c("DOWN Abundant", "Anaerobic"), c("UP Abundant", "Aerobic")),
    FP = list(c("DOWN Abundant", "Aerobic"), c("UP Abundant", "Anaerobic")))

    # Plot the TP-FP differences for each threshold
    plotPositives(positives = positives)

[Package benchdamic version 1.0.0 Index]