R: The propr Package

propr {propr} | R Documentation

## The propr Package

### Description

Welcome to the `propr` package!

To learn more about calculating proportionality, see Details.

To learn more about visualizing proportionality, see `visualize`.

To learn more about `ALDEx2` package integration, see `aldex2propr`.

To learn more about differential proportionality, see `propd`.

To learn more about compositional data analysis, and its relevance to biological count data, see the bundled vignette.

### Usage

    ## S4 method for signature 'propr'
    show(object)

    propr(counts, metric = c("rho", "phi", "phs", "cor", "vlr"),
      ivar = "clr", select, symmetrize = FALSE, alpha, p = 100)

    phit(counts, ...)

    perb(counts, ...)

    phis(counts, ...)

    corr(counts, ...)

    ## S4 method for signature 'propr'
    subset(x, subset, select)

    ## S4 method for signature 'propr'
    x[i = "all", j, tiny = FALSE]

    simplify(object)

    updateCutoffs.propr(object, cutoff, ncores)

### Arguments

`object` | A `propr` or `propd` object.
`counts` | A data.frame or matrix. A "count matrix" with subjects as rows and features as columns. Note that this matrix does not necessarily have to contain counts.
`metric` | A character string. The proportionality metric to calculate. Choose from "rho", "phi", or "phs".
`ivar` | A numeric scalar. Specifies reference feature(s) for additive log-ratio transformation. The argument will also accept feature name(s) instead of the index position(s). Set to "iqlr" to use inter-quartile log-ratio transformation. Ignore to use centered log-ratio transformation.
`select` | Optional. Use this to subset the final proportionality matrix without altering the result. Use this argument to rearrange feature order.
`symmetrize` | A logical. If `TRUE`, forces symmetry by reflecting the "lower left triangle".
`alpha` | A double. See vignette for details. Leave missing to skip Box-Cox transformation.
`p` | An integer. The number of permutation cycles.
`...` | Arguments passed to the wrapped method.
`x` | A `propr` or `propd` object.
`subset` | Subsets via `object@counts[subset, ]`. Use this argument to rearrange subject order. For backwards compatibility.
`i` | Operation used for the subset indexing. Select from "==", "=", ">", ">=", "<", "<=", "!=", or "all". For backwards compatibility.
`j` | Provide a numeric value to which to compare the proportionality measures in the `@matrix` slot. For backwards compatibility.
`tiny` | A logical scalar. Toggles whether to pass the indexed result through `simplify`. For backwards compatibility.
`cutoff` | For `updateCutoffs`, a numeric vector. this argument provides the FDR cutoffs to test. For graph functions, a numeric scalar. This argument indicates the maximum theta to include in the figure. For graph functions, a large integer will instead retrieve the top N pairs as ranked by theta.
`ncores` | An integer. The number of parallel cores to use.

### Details

Let D represent a number of features measured across N samples. This function calculates proportionality from a data set with N rows and D columns. One can think of phi as analogous to a distance matrix, except that it has no symmetry unless forced. One can think of rho as analogous to a correlation matrix. One can think of phs as either a naturally symmetric variant of phi or a monotonic variant of rho. Also, one can use `corr` to calculate correlation from log-ratio transformed data.

This function depends on a reference and uses the centered log-ratio transformation by default. The user may also specify any number of features (by index or name) to use as a reference instead. Alternatively, `ivar = "iqlr"` will transform data using the geometric mean of features with variances that fall in the inter-quartile range of all per-feature variances (based on the `ALDEx2` package).

The `propr` method calculates proportionality. This fails in the setting of zero counts. The `propr` method will use a Box-Cox transformation to approximate VLR based on the parameter α, if provided. We refer the user to the vignette for more details.

### Value

Returns a `propr` object.

### Slots

`counts`

  A data.frame. Stores the original "count matrix" input.

`alpha`

  A double. Stores the alpha value used for transformation.

`metric`

  A character string. The metric used to calculate proportionality.

`ivar`

  A vector. The reference used to calculate proportionality.

`logratio`

  A data.frame. Stores the transformed "count matrix".

`matrix`

  A matrix. Stores the proportionality matrix.

`pairs`

  A vector. Indexes the proportional pairs of interest.

`results`

  A data.frame. Stores the pairwise `propr` measurements.

`permutes`

  A list. Stores the shuffled transformed "count matrix" instances, used to reproduce permutations of `propr`.

`fdr`

  A data.frame. Stores the FDR cutoffs for `propr`.

### Methods (by generic)

`show:` Method to show `propr` object.

`subset:` Method to subset `propr` object.

`[:` Method to subset `propr` object.

### Functions

`phit:` A wrapper for `propr(counts, metric = "phi", ...)`.

`perb:` A wrapper for `propr(counts, metric = "rho", ...)`.

`phis:` A wrapper for `propr(counts, metric = "phs", ...)`.

`corr:` A wrapper for `propr(counts, metric = "cor", ...)`.

`simplify:` This convenience function takes an indexed `propr` object and subsets the object based on that index. Then, it populates the `@pairs` slot of the new object with an updated version of the original index. You can call `simplify` from within the `[` method using the argument `tiny`.

`updateCutoffs:` Use the `propr` object to permute proportionality across a number of cutoffs. Since the permutations get saved when the object is created, calling `updateCutoffs` will use the same random seed each time.

[Package propr version 4.2.6 Index]