phenopath {phenopath} | R Documentation

## PhenoPath - genomic trajectories with heterogeneous backgrounds

### Description

PhenoPath learns genomic trajectories in the presence of heterogenous environmental and genetic backgrounds. It takes input gene expression measurements that are modelled by a single unobserved factor (the "trajectory"). The regulation of genes along the trajectory is perturbed by an additional set of covariates (such as genetic or environmental status) allowing for the identification of covariate-trajectory interactions. The model is fitted using mean-field co-ordinate ascent variational inference.

### Usage

    phenopath(exprs_obj, x, sce_assay = "exprs", elbo_tol = 1e-05, z_init = 1,
      ...)

### Arguments

`exprs_obj` | Input gene expression, either An SummarizedExperiment object, or A cell-by-gene matrix of normalised expression values in log form.
`x` | The covariate vector, either The name of a column of `colData(exprs_obj)` if `exprs_obj` is an `SummarizedExperiment`, or A numeric of factor vector of length equal to the number of cells, or A formula from which to build a model matrix from `colData(exprs_obj)`, if `exprs_obj` is a SummarizedExperiment
`sce_assay` | The assay from `exprs_obj` to use as expression if `exprs_object` is a `SummarizedExperiment`
`elbo_tol` | The relative pct change in the ELBO below which is considered converged. See convergence section in details below.
`z_init` | The initialisation of the latent trajectory. Should be one of A positive integer describing which principal component of the data should be used for initialisation (default 1), or A numeric vector of length number of samples to be used directly for initialisation, or The text character `"random"`, for random initialisation from a standard normal distribution.
`...` | Additional arguments to be passed to `clvm`. See description below for more details or call `?clvm`.

### Details

Input expression

If an `SummarizedExperiment` is provided, `assay(exprs_obj, sce_assay)` is used. This is assumed to be in a form that is suitably normalised and approximately normal, such as the log of TPM values (plus a suitable offset) or similar.

Encoding covariates

See the vignette.

Convergence of variational inference

It is strongly recommended to call `plot_elbo(phenopath_fit)` after the fitting procedure to ensure the ELBO has approximately converged (though convergence metrics are printed during the fitting process). For a good introduction to variational inference see Blei, D.M., Kucukelbir, A. & McAuliffe, J.D., 2017. Variational Inference: A Review for Statisticians. Journal of the American Statistical Association.

Additional arguments

Addition arguments to `clvm` are passed via `...`. For full documentation, call `?clvm`. Some notable options:

- `thin` - The ELBO is expensive to compute for larger datasets. The model will compute the ELBO and compare convergence every `thin` iterations.

- `q` and `tau_q` - Priors (such as capture times) for the latent space. Note that `model_mu` should be true if `q` is non-zero.

- `scale_y` By default the input expression is centre-scaled for each gene. If `scale_y` is `FALSE` this does not happen - but note that `model_mu` should be `TRUE` in such a case.

### Value

An S3 structure with the following entries:

- `m_z` The converged mean estimates of the trajectory

- `s_z` The converged standard deviation estimates of z

- `m_beta` A P-by-G matrix of interaction coefficients

- `s_beta` A P-by-G matrix of interaction standard deviations

### See Also

`clvm` for the underlying CAVI function, `trajectory` to extract the latent trajectory, `interaction_effects` for the interaction effect sizes, `significant_interactions` for the results of Bayesian significance testing.

### Examples

    sim <- simulate_phenopath() # returns a list with gene expression in y and covariates in x
    fit <- phenopath(sim$y, sim$x, elbo_tol = 1e-2)

    # Extract the trajectory
    z <- trajectory(fit)

[Package phenopath version 1.14.0 Index]