Package 'rsemflow'

Annotate Ensembl gene IDs using a local Bioconductor OrgDb

Description

Adds the stable Ensembl ID (version suffix removed), gene symbol, Entrez ID, and description from org.Hs.eg.db or org.Mm.eg.db. The original RSEM gene_id is always kept. When an Ensembl ID maps to several Entrez records, the record with the most filled fields is kept. annotation_status is mapped when the OrgDb returned at least one of the symbol, Entrez ID, or description, and unmapped otherwise (including non-Ensembl IDs such as spike-ins).

Usage

annotate_ensembl(study, species = "auto")

Arguments

study	A rsemflow_study or study path.
species	auto, human, or mouse.

Value

A gene annotation data frame.

---

Annotate genes from a GTF file

Description

Reads the gene records of the GTF used to build the RSEM reference and returns gene_name, gene_type/gene_biotype, and description. IDs are matched on the full versioned ID first and on the stable Ensembl ID second.

Usage

annotate_gtf(study, gtf)

Arguments

study	A rsemflow_study or study path.
gtf	Path to a GTF or GTF.GZ file.

Value

A gene annotation data frame.

---

RSEMflow command-line entry point

Description

Parses ⁠rsemflow <module> <action> [options]⁠ and calls the matching R function. Options use the prefixes ⁠--i-⁠ (inputs), ⁠--m-⁠ (metadata), ⁠--p-⁠ (parameters), and ⁠--o-⁠ (outputs). Add --help at any level for usage.

Usage

cli_main(args = commandArgs(trailingOnly = TRUE))

Arguments

args	Character vector of command-line arguments.

Details

The installed launcher script (system.file("exec", "rsemflow", package = "rsemflow")) calls this function. Without the launcher, use ⁠Rscript -e "rsemflow::cli_main()" <module> <action> [options]⁠.

Value

Invisibly returns zero on success. Errors are raised as R errors.

Examples

cli_main("--help")
cli_main(c("differential", "deseq2", "--help"))

---

Compute sample correlation

Description

Compute sample correlation

Usage

compute_correlation(
  study,
  transform = c("vst", "log2-tpm"),
  method = c("pearson", "spearman")
)

Arguments

study	A rsemflow_study or study path.
transform	vst or log2-tpm.
method	pearson or spearman.

Value

A sample-by-sample correlation matrix.

---

Compute PCA tables from transformed expression

Description

Selects the ntop genes with the highest variance after transformation and runs stats::prcomp() with samples as observations, centering on, and no scaling.

Usage

compute_pca(
  study,
  transform = c("vst", "log2-tpm"),
  ntop = 500L,
  components = 10L
)

Arguments

study	A rsemflow_study or path.
transform	vst or log2-tpm.
ntop	Number of most variable genes to use.
components	Maximum number of PCs to return.

Value

A list containing scores, loadings, and variance data frames, plus the transform and the number of genes used (ntop).

Examples

ex <- system.file("extdata", "example", package = "rsemflow")
study <- read_rsem_study(file.path(ex, "data"), file.path(ex, "metadata.tsv"))
p <- compute_pca(study, ntop = 100, components = 3)
p$variance

---

Run metadata-driven DESeq2 differential expression

Description

Fits a DESeq2 model from the tximport-derived counts of a study and returns one result table per comparison.

Usage

differential_deseq2(
  study,
  formula,
  term,
  metadata = NULL,
  reference = character(),
  contrast = character(),
  at = character(),
  test = c("wald", "lrt"),
  reduced = NULL,
  categorical = character(),
  numeric = character(),
  alpha = 0.05
)

Arguments

study	A rsemflow_study or study path.
formula	R formula or formula string.
term	Metadata variable or interaction term to report.
metadata	Optional replacement metadata path/data.frame.
reference	Character vector like condition::Control.
contrast	Character vector like ⁠condition::Drug::Control⁠.
at	Optional conditioning specification like genotype::KO; currently supports one simple-effect condition with an explicit contrast.
test	wald or lrt.
reduced	Reduced formula required for LRT.
categorical	Metadata columns to force categorical.
numeric	Metadata columns to force numeric.
alpha	Significance threshold passed to DESeq2 results.

Details

Which tables are produced depends on term:

• a categorical variable: every level versus the reference level;

• a numeric variable: the per-unit coefficient;

• an interaction such as genotype:treatment: every interaction coefficient.

Extra comparisons can be requested with contrast. With at, a single simple effect is returned instead (for example the treatment effect within one genotype in a ~ genotype * treatment model). With test = "lrt", one omnibus table is returned and log2FoldChange/lfcSE are set to NA because the likelihood-ratio test has no single direction.

Log fold changes are not shrunk.

Value

A list with the fitted DESeqDataSet (dds), the metadata used, the formula(s), the design matrix, a contrast manifest, and the named result tables (results).

Examples

ex <- system.file("extdata", "example", package = "rsemflow")
study <- read_rsem_study(file.path(ex, "data"), file.path(ex, "metadata.tsv"))
de <- differential_deseq2(
  study,
  formula = ~ batch + condition,
  term = "condition",
  reference = "condition::Control"
)
head(de$results$condition_Drug_vs_Control)

---

Normalize or transform expression values

Description

• vst: DESeq2 size factors, then varianceStabilizingTransformation(blind = TRUE).

• normalized-counts: counts divided by DESeq2 size factors (with the tximport average-length offsets).

• log2-tpm: log2(TPM + 1).

Usage

normalize_expression(study, method = c("vst", "normalized-counts", "log2-tpm"))

Arguments

study	A rsemflow_study or study path.
method	One of vst, normalized-counts, or log2-tpm.

Value

A gene-by-sample numeric matrix.

---

Import RSEM gene-level results and metadata

Description

Finds every ⁠*.genes.results⁠ file in rsem_dir, takes the sample ID from the file name (S01.genes.results -> S01), matches the files to the sample_id column of metadata, and imports the counts with tximport(type = "rsem").

Usage

read_rsem_study(
  rsem_dir,
  metadata,
  categorical = character(),
  numeric = character()
)

Arguments

rsem_dir	Directory containing ⁠*.genes.results⁠ files.
metadata	Path to TSV or CSV metadata with a sample_id column.
categorical	Optional metadata columns to force to categorical.
numeric	Optional metadata columns to force to numeric.

Details

Import stops when a file lacks the standard RSEM columns, when sample IDs do not match the metadata one-to-one, or when the files do not share an identical gene table (same IDs in the same order, without duplicates).

Metadata columns whose values all parse as numbers become numeric; the rest become factors. Use categorical/numeric to override.

Value

An object of class rsemflow_study.

Examples

ex <- system.file("extdata", "example", package = "rsemflow")
study <- read_rsem_study(file.path(ex, "data"), file.path(ex, "metadata.tsv"))
study

---

Read and write RSEMflow studies

Description

write_study() saves the study as study.rds plus plain TSV copies of the metadata, the expected-count, TPM, and effective-length matrices, a sample-to-file table, and study-info.tsv. read_study() restores the study.rds.

Usage

read_study(path)

write_study(study, path)

Arguments

path	Study directory or a study.rds path.
study	A rsemflow_study.

Value

read_study() returns an object of class rsemflow_study; write_study() invisibly returns path.

Examples

ex <- system.file("extdata", "example", package = "rsemflow")
study <- read_rsem_study(file.path(ex, "data"), file.path(ex, "metadata.tsv"))
out <- file.path(tempdir(), "study")
write_study(study, out)
list.files(out)
identical(read_study(out)$sample_ids, study$sample_ids)

---

Run preranked GSEA

Description

Run preranked GSEA

Usage

run_gsea(
  differential,
  species = "auto",
  collection = "hallmark",
  subcollection = NULL,
  genesets = NULL,
  rank = "stat",
  min_size = 15L,
  max_size = 500L,
  eps = 0,
  seed = 42L
)

Arguments

differential	Differential-expression table or path.
species	auto, human, or mouse.
collection	MSigDB collection alias or raw collection code.
subcollection	Optional MSigDB subcollection.
genesets	Optional named gene-set list or GMT path.
rank	Column used as ranking statistic, default stat.
min_size	Minimum mapped gene-set size.
max_size	Maximum mapped gene-set size.
eps	Passed to fgseaMultilevel.
seed	Random seed for fgseaMultilevel, which estimates p-values by sampling. The same seed gives the same table.

Details

Gene IDs are matched to gene sets by stable Ensembl gene ID. When several rows share a stable ID, the row with the largest absolute ranking statistic is kept.

Unsigned statistics, such as the stat column of an LRT table, are rejected because preranked GSEA needs a direction.

Value

A data frame of GSEA results, sorted by padj and then by decreasing ⁠|NES|⁠.

Examples

ids <- sprintf("ENSG%011d", 1:100)
de <- data.frame(ensembl_gene_id = ids, stat = seq(5, -5, length.out = 100))
sets <- list(UP = ids[1:20], DOWN = ids[81:100], MIXED = ids[seq(1, 100, 5)])
run_gsea(de, genesets = sets, min_size = 10, max_size = 50)

---

Run GSVA or ssGSEA pathway scoring

Description

Scores each gene set in each sample from log2(TPM + 1). Rows sharing a stable Ensembl ID are averaged first. GSVA uses a Gaussian kernel (kcdf = "Gaussian"). Scores are descriptive; no test between groups is run.

Usage

run_gsva(
  study,
  species = "auto",
  collection = "hallmark",
  subcollection = NULL,
  genesets = NULL,
  method = c("gsva", "ssgsea"),
  min_size = 10L,
  max_size = 500L
)

Arguments

study	A rsemflow_study or study path.
species	auto, human, or mouse.
collection	MSigDB collection alias or raw collection code.
subcollection	Optional MSigDB subcollection.
genesets	Optional named list or GMT file.
method	gsva or ssgsea.
min_size	Minimum gene-set size.
max_size	Maximum gene-set size.

Value

A pathway-by-sample data frame with gene-set metadata columns.

---

Summarize expression-level QC statistics

Description

Sample- and gene-level summaries computed from the RSEM expected counts and TPM. A gene is "detected" when its expected count is above zero. These are descriptive numbers only; no sample is flagged or removed.

Usage

summarize_study(study)

Arguments

study

A rsemflow_study or path to a study.

Value

A list with samples and genes data frames.

Examples

ex <- system.file("extdata", "example", package = "rsemflow")
study <- read_rsem_study(file.path(ex, "data"), file.path(ex, "metadata.tsv"))
s <- summarize_study(study)
s$samples

---