Package 'isoformic'

Title: Isoform-Level Biological Interpretation of Transcriptomic Data
Description: Isoform-level biological interpretation of transcriptomic data. Provides the 'IsoformicExperiment' class, a disk-backed (Parquet) container holding transcript, gene and exon level data for the same samples, fast DuckDB based readers for annotations and quantifications, summaries of isoform usage and diversity, and plots of isoform-level differential expression, expression profiles and genomic context.
Authors: Lucio Rezende Queiroz [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-6090-1834>), Izabela Mamede Conceicao [aut, ctb] (ORCID: <https://orcid.org/0000-0002-0707-5588>), Carlos Mata-Machado [aut, ctb] (ORCID: <https://orcid.org/0009-0005-6615-6563>), Luigi Marchionni [aut, ctb] (ORCID: <https://orcid.org/0000-0002-7336-8071>), Gloria Franco [aut, ctb] (ORCID: <https://orcid.org/0000-0001-5245-2365>)
Maintainer: Lucio Rezende Queiroz <[email protected]>
License: MIT + file LICENSE
Version: 0.1.3
Built: 2026-11-13 02:54:31 UTC
Source: https://github.com/luciorq/isoformic

Help Index


Attach Extra Columns to the Annotation Tables

Description

Joins columns of an external per-transcript or per-gene table into the annotation directory (persisted in the Parquet tables, so every object using the annotation sees them and caches refresh automatically). This is the hook for evidence that the package does not compute itself: FANTOM CAGE clusters, GTEx dominant isoforms per tissue, Ribo-seq translation calls, NMD-inhibition responses, protein domain retention, long-read full-length counts. A column named productivity_evidence with values "productive" / "unproductive" overrides the call of transcript_productivity().

Usage

add_annotation_columns(
  x,
  table,
  level = c("transcript", "gene"),
  by = NULL,
  prefix = NULL
)

Arguments

x

An annotation directory path or an IsoformicExperiment.

table

A data frame, or a path to a tabular file readable by read_tabular().

level

"transcript" (default) or "gene".

by

Name of the key column in table; defaults to transcript_id/gene_id, or the first column.

prefix

Optional prefix added to the new column names.

Value

The annotation directory path, invisibly.

Examples

gff <- system.file("extdata", "example.gff3", package = "isoformic")
annot <- prepare_isoformic_annotation(gff, output_path = tempdir(), annot_name = "evidence_demo")
tx <- read_parquet(file.path(annot, "annot_data_transcripts.parquet"))
evidence <- data.frame(
  transcript_id = tx$transcript_id[1:2],
  riboseq_translated = c(TRUE, FALSE),
  productivity_evidence = c("productive", "unproductive")
)
add_annotation_columns(annot, evidence)
tx <- read_parquet(file.path(annot, "annot_data_transcripts.parquet"))
head(tx[, c("transcript_id", "riboseq_translated")], 3)

Attach FANTOM CAT Tables to an Annotation

Description

FANTOM CAT distributes, next to the GTF, an ID mapping table (geneID, transcriptID, CAGEClusterID) and a gene information table (geneClass, geneCategory, TIEScore_tier, splicingType, directionality, transposable element associations, ...). This function joins them into the annotation directory: the CAGE cluster (the CAGE-defined promoter of each transcript) becomes cage_cluster_id, with its coordinates parsed into cage_cluster_seqid, cage_cluster_start, cage_cluster_end, and the gene information columns are added to the gene table in snake case. See download_fantom_cat_tables().

Usage

add_fantom_cat_tables(x, id_mapping, gene_info = NULL)

Arguments

x

An annotation directory path or an IsoformicExperiment.

id_mapping

Path (or data frame) of the ID mapping table.

gene_info

Optional path (or data frame) of the gene info table.

Value

The annotation directory path, invisibly.

Examples

## Not run: 
gtf <- download_reference(reference = "fantom", version = "lv3_robust")
tables <- download_fantom_cat_tables("lv3_robust")
annot <- prepare_isoformic_annotation(gtf)
add_fantom_cat_tables(annot, tables[["id_mapping"]], tables[["gene_info"]])

## End(Not run)

Add SQANTI3 Structural Categories to an Annotation

Description

Long-read transcript catalogs (IsoSeq, FLAIR, Bambu, StringTie) carry no biotype for novel transcripts. SQANTI3 classifies every isoform against a reference (⁠*_classification.txt⁠: isoform, structural_category, associated_gene, associated_transcript, subcategory, ...). add_sqanti_classification() writes those categories into the transcript_type column of an annotation directory (and the associated reference transcript / gene into source_transcript_id, source_gene_id and gene_name when they are missing), so the SQANTI categories behave like transcript types everywhere in the package (plots, enrichment by category, tx_diversity()). The categories are part of tx_type_palette().

Usage

add_sqanti_classification(x, classification, overwrite_types = TRUE)

Arguments

x

An annotation directory path or an IsoformicExperiment (its annotation directory is modified in place and caches refresh automatically).

classification

Path to the SQANTI3 classification file (tab separated, optionally gzipped) or a data frame with at least the isoform and structural_category columns.

overwrite_types

Logical. Replace existing transcript types (default TRUE); with FALSE only missing types are filled.

Value

The annotation directory path, invisibly.

Examples

gff <- system.file("extdata", "example.gff3", package = "isoformic")
annot <- prepare_isoformic_annotation(gff, output_path = tempdir(), annot_name = "sqanti_demo")
tx <- read_parquet(file.path(annot, "annot_data_transcripts.parquet"))
classification <- data.frame(
  isoform = tx$transcript_id[1:3],
  structural_category = c("full-splice_match", "novel_in_catalog", "novel_not_in_catalog"),
  associated_gene = "RBPJ",
  associated_transcript = c(tx$transcript_id[1], "novel", "novel")
)
add_sqanti_classification(annot, classification)
tx <- read_parquet(file.path(annot, "annot_data_transcripts.parquet"))
head(tx[, c("transcript_id", "transcript_type")], 4)

Train the Coding Potential Model

Description

Builds the hexamer log-odds table and the logistic regression used by coding_potential() from a set of coding ORF sequences and non-coding transcript sequences, and writes both as Parquet files. The shipped model was trained on GENCODE human protein-coding CDS versus lncRNA transcripts by data-raw/build_coding_model.R; rerun that script to refresh it for a new GENCODE release or another organism.

Usage

build_coding_model(
  coding_cds,
  coding,
  noncoding,
  output_dir,
  min_orf_length = 90L,
  pseudocount = 1
)

Arguments

coding_cds

Character vector of CDS sequences (start to stop codon), used to build the hexamer table.

coding

Character vector of full-length coding transcript sequences (mRNAs), the positive class of the logistic model.

noncoding

Character vector of non-coding transcript sequences, the negative class (and the hexamer background).

output_dir

Directory receiving hexamer_logodds.parquet and coding_model_coefficients.parquet.

min_orf_length

Minimum ORF length used when scoring the training sequences.

pseudocount

Pseudocount added to hexamer counts.

Value

A list with the hexamer table, the fitted glm and the training accuracy, invisibly.

Examples

## Not run: 
build_coding_model(cds_sequences, mrna_sequences, lncrna_sequences, output_dir = "coding_model")

## End(Not run)

Build the Frozen Datasets from Their Sources

Description

Each function downloads the source files of one frozen dataset (see frozen_datasets()) into the sources cache, converts them to the Parquet table used by the package and returns the file path. They are what fetch_frozen_data() runs when a frozen file cannot be downloaded, and what data-raw/build_frozen_data.R runs to publish a new version. The resulting tables:

  • build_frozen_appris(): one row per transcript with appris_annotation (PRINCIPAL:1 to ALTERNATIVE:2, MINOR), appris_score, the method scores (firestar_residues, matador_structure, corsair_conservation, spade_domain_score, thump_tm_helices, crash_signal, trifid_score), protein_length, ccds_id and mane label.

  • build_frozen_appris_domains(): one row per Pfam domain per transcript with its genomic span (seqid, start_pos, end_pos, strand), pfam_acc, pfam_name, evalue, pep_start, pep_end.

  • build_frozen_riboseq_orfs(): one row per Ribo-seq ORF with phase, genomic span, block_starts/block_ends (1-based, ⁠;⁠-separated), orf_type, gene_id, gene_name, transcript_ids (compatible transcripts, phase 1 only), replicated and studies.

  • build_frozen_nmd_exons(): one row per validated NMD-inducing exon with seqid, start_pos, end_pos, strand, the flanking exons, nmd_transcript_ids, non_nmd_transcript_ids, gene_id, gene_name. Reading the supplementary spreadsheet needs the readxl package.

  • build_frozen_polyasite(): one row per poly(A) site cluster with seqid, start_pos, end_pos, cleavage_pos, strand, tpm, frac_samples, n_protocols, site_class (TE terminal exon, EX exon, IN intron, DS downstream, AE/AI/AU antisense, IG intergenic) and signals.

  • build_frozen_gtex(): one row per transcript and tissue with median_tpm and n_samples (GTEx v8, RSEM transcript TPM; identifiers are GENCODE v26, stored without version).

Usage

build_frozen_appris(output_path = ":cache:", sources_dir = NULL)

build_frozen_appris_domains(output_path = ":cache:", sources_dir = NULL)

build_frozen_riboseq_orfs(output_path = ":cache:", sources_dir = NULL)

build_frozen_nmd_exons(output_path = ":cache:", sources_dir = NULL)

build_frozen_polyasite(output_path = ":cache:", sources_dir = NULL)

build_frozen_gtex(output_path = ":cache:", sources_dir = NULL)

Arguments

output_path

Directory receiving the Parquet file (default: the frozen-data cache).

sources_dir

Directory holding (or receiving) the source files; default: ⁠get_isoformic_cache("sources", <name>, <version>)⁠.

Value

The path of the written Parquet file, invisibly.

Examples

## Not run: 
build_frozen_riboseq_orfs()

## End(Not run)

Differential Expression Results in an IsoformicExperiment

Description

An IsoformicExperiment stores differential expression results for transcripts (det) and genes (deg) in its dea property, together with the significance cutoffs used to flag features. Results can come from any tool: on assignment the tables are standardised to the column names log2FC, pvalue and qvalue (see Details), checked against the annotation, and stored as tibbles.

  • de_tx(x) / de_gene(x): results with an added det_sig / deg_sig column ("yes"/"no") computed from the cutoffs, sorted by absolute log2FC. Cutoffs can be overridden per call.

  • de_tx(x) <- value / de_gene(x) <- value: set results.

  • de_cutoffs(x) / de_cutoffs(x) <- value: the stored cutoffs, a list with log2fc (default 1), pvalue (default 0.05) and use_fdr (default TRUE, i.e. compare qvalue rather than pvalue).

  • de_table(x): a long table combining gene and transcript results, one row per feature, with feature_id, feature_name, feature_type ("gene" or the transcript type), gene_id, gene_name, log2FC, pvalue, qvalue and is_de. This is the input of plot_log2fc().

Usage

de_tx(
  self,
  log2fc_cutoff = NULL,
  pvalue_cutoff = NULL,
  use_fdr = NULL,
  sig_only = FALSE,
  ...
)

de_gene(
  self,
  log2fc_cutoff = NULL,
  pvalue_cutoff = NULL,
  use_fdr = NULL,
  sig_only = FALSE,
  ...
)

de_tx(self) <- value

de_gene(self) <- value

de_cutoffs(self, ...)

de_cutoffs(self) <- value

de_table(self, ...)

Arguments

self

An IsoformicExperiment.

log2fc_cutoff, pvalue_cutoff, use_fdr

Optional per-call overrides of the stored cutoffs.

sig_only

Logical, return only significant features.

...

Passed on to methods.

value

A data frame of results (⁠de_tx<-⁠, ⁠de_gene<-⁠) or a list of cutoffs (⁠de_cutoffs<-⁠).

Details

Recognised column synonyms: log2FoldChange/logFC for log2FC; padj/FDR/adj.P.Val/svalue for qvalue; PValue/P.Value for pvalue. Row names are used as IDs when no ID column is present, and GENCODE-style |-suffixed transcript IDs are truncated. When qvalue is absent it is computed with Benjamini-Hochberg adjustment of pvalue.

Value

Tibbles, or the modified object for replacement functions.

Examples

iso <- example_isoformic()
de_cutoffs(iso)
head(de_tx(iso))
head(de_gene(iso, sig_only = TRUE))
head(de_table(iso))

de_cutoffs(iso) <- list(log2fc = 0.5)
sum(de_tx(iso)$det_sig == "yes")

Transcriptomic Diversity Summaries

Description

These generics quantify how expression is distributed across the isoforms of each gene, which is the question an IsoformicExperiment is built to answer. All computations use matrix operations on the cached assays and scale to full transcriptome experiments.

  • isoform_fraction(x): matrix (transcripts x samples) of the fraction of its gene's expression carried by each transcript. NA where the gene is not expressed in a sample.

  • tx_diversity(x): one row per gene summarising isoform usage: number of annotated, assayed and expressed isoforms, number of transcript types, the dominant isoform and its mean fraction, and the effective number of isoforms (⁠exp(Shannon entropy)⁠ of the mean isoform fractions, 1 = a single isoform carries all expression).

  • dominant_isoform(x, group): the dominant isoform of each gene, overall or per level of a col_data column, flagging genes whose dominant isoform changes between groups (dominant_switch).

  • isoform_switches(x): relates transcript- and gene-level differential expression per gene: counts of significant isoforms up and down, the gene-level call and a switch_type classification ("opposite_direction", "det_not_deg", "consistent").

  • exon_diversity(x, gene_name): per gene, the number of distinct exons, how many are constitutive (shared by all isoforms) versus alternative, and the mean number of exons per isoform.

  • haplotype_summary(x, group): for haplotype-resolved annotations (see merge_annotations()), expression of each gene per haplotype, the haplotype fraction (allelic imbalance), the dominant isoform of each haplotype (compared through source_transcript_id) and whether the dominant isoform differs between haplotypes (haplotype_isoform_switch). Genes are matched across haplotypes by source_gene_id, falling back to gene_name.

dominant_isoform() also reports dominant_is_canonical, whether the dominant isoform is the MANE Select / Ensembl canonical / RefSeq Select transcript of its gene. When the object carries uncertainty tables (see add_uncertainty()) it adds dominant_inf_rv, the inferential relative variance of the dominant isoform, and dominant_ambiguous, whether it cannot be told apart from a sibling isoform. isoform_switches() adds n_det_confident, the number of significant isoforms with high confidence, once de_confidence() results are stored.

Usage

isoform_fraction(self, assay = "abundance", ...)

tx_diversity(
  self,
  assay = "abundance",
  min_expr = 1,
  min_samples = 1L,
  gene_name = NULL,
  ...
)

dominant_isoform(
  self,
  group = NULL,
  assay = "abundance",
  gene_name = NULL,
  min_expr = 0,
  levels = NULL,
  ...
)

isoform_switches(self, gene_name = NULL, confident_only = FALSE, ...)

exon_diversity(self, gene_name = NULL, ...)

haplotype_summary(
  self,
  group = NULL,
  assay = "abundance",
  gene_name = NULL,
  levels = NULL,
  ...
)

Arguments

self

An IsoformicExperiment.

assay

Name of the transcript assay to use (default "abundance", falling back to the first assay).

...

Passed on to methods.

min_expr

Minimum assay value for a transcript to count as expressed in a sample.

min_samples

Minimum number of samples in which a transcript must be expressed to count as expressed.

gene_name

Optional character vector of gene names or IDs to restrict the result to.

group

Name of a col_data column defining sample groups, or NULL for all samples together.

levels

Levels of group to use, in this order. Samples of other groups are ignored, as if the object had been subset to these samples. NULL takes all the levels of group.

confident_only

Logical. Count only the significant isoforms with high confidence (see de_confidence()) in isoform_switches().

Value

A matrix for isoform_fraction(), tibbles otherwise.

Examples

iso <- example_isoformic()
isoform_fraction(iso)[1:3, 1:3]
head(tx_diversity(iso))
dominant_isoform(iso, group = "condition")
isoform_switches(iso)
exon_diversity(iso, gene_name = c("RBPJ", "EGFR"))

Protein Domain Retention of Isoforms

Description

Compares the Pfam domains of every isoform with those of the canonical isoform of its gene, using the APPRIS SPADE domain coordinates (frozen dataset appris_domains, frozen_data). For isoforms present in APPRIS the domain sets are compared directly. For other isoforms (novel transcripts) the genomic span of each canonical domain is projected onto the isoform: a domain is retained when the isoform covers the same exonic bases over the domain span and its ORF (see transcript_orfs(), or the annotated CDS) extends over it without a frameshift, partial when only part of the span is covered, and lost otherwise.

An altered_productive isoform that keeps all domains of the canonical protein is a milder event than one that loses a domain; the domain_retention_fraction column grades this and is included in transcript_productivity() output when the dataset is available.

Usage

domain_retention(self, gene_name = NULL, domains = NULL, ...)

Arguments

self

An IsoformicExperiment.

gene_name

Optional genes (names or IDs) to restrict the result to.

domains

Data frame or Parquet path of the domain table; NULL fetches the frozen appris_domains dataset.

...

Passed on to methods.

Value

A tibble with one row per transcript: n_domains_canonical, n_retained, n_partial, n_lost, domains_lost (Pfam names) and domain_retention_fraction (NA when the canonical isoform has no domain).

Examples

## Not run: 
iso <- example_isoformic()
domain_retention(iso, gene_name = "RBPJ")

## End(Not run)

Download the FANTOM CAT Companion Tables

Description

Fetches, for one FANTOM CAT level, the ID mapping table (transcript to CAGE cluster), the gene information table and the CAGE cluster BED file, which add_fantom_cat_tables() joins into an annotation directory.

Usage

download_fantom_cat_tables(
  level = c("lv3_robust", "lv4_stringent", "lv2_permissive", "lv1_raw"),
  tables = c("id_mapping", "gene_info", "cage_clusters"),
  output_path = ":cache:",
  timeout_limit = 3600,
  method = "auto"
)

Arguments

level

FANTOM CAT level: "lv3_robust" (default), "lv1_raw", "lv2_permissive" or "lv4_stringent".

tables

Which tables to download.

output_path

Directory where the file is saved. Defaults to ":cache:", the package cache (see get_isoformic_cache()).

timeout_limit

Maximum time in seconds for the download. Takes precedence over options("timeout"). Defaults to 3600.

method

Method used by utils::download.file(). Defaults to "auto".

Value

A named character vector of file paths (id_mapping, gene_info, cage_clusters).

Examples

## Not run: 
tables <- download_fantom_cat_tables("lv3_robust")
tables

## End(Not run)

Download HPRC Per-Haplotype CAT Annotations

Description

Downloads the Human Pangenome Reference Consortium year-1 CAT/Liftoff gene annotations of an assembled sample, one GFF3 per haplotype, lifted from GENCODE v38 onto the sample's own assembly in CHM13 or GRCh38 coordinates. The files keep GENCODE identifiers in source_gene / source_transcript, so merge_annotations() and haplotype_summary() can compare haplotypes.

Usage

download_hprc_annotation(
  sample,
  haplotype = c(1L, 2L),
  assembly = c("chm13", "hg38"),
  output_path = ":cache:",
  timeout_limit = 3600,
  method = "auto"
)

Arguments

sample

HPRC sample ID, for example "HG00438" or "HG002".

haplotype

Haplotype numbers to download, 1, 2 or c(1, 2) (default).

assembly

Coordinate space of the CAT run: "chm13" (default) or "hg38".

output_path

Directory where the file is saved. Defaults to ":cache:", the package cache (see get_isoformic_cache()).

timeout_limit

Maximum time in seconds for the download. Takes precedence over options("timeout"). Defaults to 3600.

method

Method used by utils::download.file(). Defaults to "auto".

Value

A named character vector of file paths (names hap1, hap2), ready for merge_annotations().

Examples

## Not run: 
files <- download_hprc_annotation("HG00438")
merged <- merge_annotations(files, annot_name = "HG00438_chm13")
merged

## End(Not run)

Download Reference Annotations and Sequences

Description

Downloads annotation (GFF3/GTF) and sequence (transcript or genome FASTA) files from the main public providers:

  • "gencode" (default): any GENCODE release for human (GRCh38) or mouse (GRCm39), including future releases.

  • "ensembl": any Ensembl release, for any species of any division (vertebrates, plants, metazoa, fungi, protists).

  • "ncbi": any NCBI assembly by accession (for example GCF_009914755.1 for T2T-CHM13v2.0, GCF_000001405.40 for GRCh38.p14).

  • "t2t": shorthand for ⁠reference = "ncbi", accession = "GCF_009914755.1"⁠ (telomere-to-telomere T2T-CHM13v2.0).

  • "mane": MANE (Matched Annotation from NCBI and EMBL-EBI) releases, the canonical transcript per protein-coding gene, in Ensembl or RefSeq coordinates and identifiers.

  • "fantom": the FANTOM CAT transcriptome assembly (Hon et al. 2017; GRCh37/hg19) at one of its levels (version = "lv3_robust" by default; "lv1_raw", "lv2_permissive", "lv4_stringent"), GTF only. FANTOM6 analyses use the lv3 robust catalog. The companion ID mapping, gene information and CAGE cluster tables come from download_fantom_cat_tables().

Instead of assuming file names, the function lists the release directory on the server and picks the matching file, so new releases and new genome patch versions (for example GRCh38.p15) work without a package update. Files already present in output_path are not downloaded again. Any other file reachable by URL (for example the T2T consortium Liftoff GFF3 files) can be cached the same way with download_reference_url(), and HPRC per-haplotype annotations with download_hprc_annotation().

Usage

download_reference(
  version = NULL,
  reference = c("gencode", "ensembl", "ncbi", "t2t", "mane", "fantom"),
  organism = c("human", "mouse"),
  file_type = c("gff", "gtf", "fasta", "ncrna_fasta", "genome_fasta", "polya"),
  region = c("all", "chr", "primary"),
  species = NULL,
  division = c("vertebrates", "plants", "metazoa", "fungi", "protists"),
  accession = NULL,
  mane_source = c("ensembl", "refseq"),
  output_path = ":cache:",
  timeout_limit = 3600,
  method = "auto"
)

Arguments

version

Release version. GENCODE: the release number ("50", 50, or "M39" / "39" for mouse; default "50"). Ensembl: the release number ("116"); NULL (default) uses the current release. MANE: "1.5"; NULL uses the current release. NCBI/T2T: ignored (the accession identifies the assembly version).

reference

One of "gencode", "ensembl", "ncbi", "t2t", "mane", "fantom".

organism

"human" (default) or "mouse". For Ensembl it sets the default species (homo_sapiens / mus_musculus).

file_type

"gff" (default), "gtf", "fasta" (transcript sequences; for Ensembl the cdna.all file), "ncrna_fasta" (Ensembl non-coding transcript sequences), "genome_fasta" (genome sequence; not provided by MANE) or "polya" (GENCODE manually annotated poly(A) sites and signals, polyAs.gff3.gz; see polya_sites()).

region

Annotation flavour: "all" (default; reference chromosomes, patches, haplotypes and scaffolds), "chr" (reference chromosomes only) or "primary" (primary assembly). For file_type = "genome_fasta", "primary" selects the primary assembly genome and the other values the full patched / toplevel genome. Ignored for NCBI and MANE.

species

Ensembl species name in lower snake case ("homo_sapiens", "arabidopsis_thaliana"). Defaults from organism.

division

Ensembl division: "vertebrates" (default, the main Ensembl site), "plants", "metazoa", "fungi" or "protists".

accession

NCBI assembly accession (GCF_... or GCA_...), required for reference = "ncbi".

mane_source

Identifier space of MANE files: "ensembl" (default) or "refseq".

output_path

Directory where the file is saved. Defaults to ":cache:", the package cache (see get_isoformic_cache()).

timeout_limit

Maximum time in seconds for the download. Takes precedence over options("timeout"). Defaults to 3600.

method

Method used by utils::download.file(). Defaults to "auto".

Value

The full path to the downloaded (or already present) file.

Errors

The function fails early with a specific condition class:

  • isoformic_download_reference_no_internet_error: no connection.

  • isoformic_download_reference_release_not_found_error: the release (or species, assembly) directory does not exist; for GENCODE the message lists the latest available releases.

  • isoformic_download_reference_file_not_found_error: the release exists but has no file of the requested type; the message lists the candidate files found.

  • isoformic_download_reference_error: the transfer failed or produced an empty file (partial files are removed).

Matching annotation and sequences

Salmon indices must be built from the transcript FASTA of the same provider and release as the annotation directory, so that transcript IDs match: GENCODE FASTA headers are |-separated (handled by ignore_after_bar), Ensembl cdna.all headers carry the versioned transcript ID first, NCBI rna.fna headers carry the RefSeq accession, and MANE provides both identifier spaces. For lifted annotations (T2T consortium Liftoff, HPRC CAT) extract the FASTA from the assembly with ⁠gffread -w transcripts.fa -g assembly.fa annotation.gff3⁠.

Examples

## Not run: 
# GENCODE
gff_file <- download_reference(version = "50", file_type = "gff")
gtf_file <- download_reference(version = "50", file_type = "gtf", region = "chr")
gff_file_mouse <- download_reference(version = "M39", organism = "mouse")
genome_file <- download_reference(version = "50", file_type = "genome_fasta")

# Ensembl: current human release, Arabidopsis from Ensembl Plants
ens_gff <- download_reference(reference = "ensembl")
ens_cdna <- download_reference(reference = "ensembl", file_type = "fasta")
ath_gff <- download_reference(
  reference = "ensembl", division = "plants", species = "arabidopsis_thaliana"
)

# NCBI assemblies by accession, and the T2T-CHM13v2.0 shorthand
t2t_gff <- download_reference(reference = "t2t", file_type = "gff")
t2t_fasta <- download_reference(reference = "t2t", file_type = "fasta")
grch38_gff <- download_reference(reference = "ncbi", accession = "GCF_000001405.40")

# MANE canonical transcripts (Ensembl identifiers)
mane_gff <- download_reference(reference = "mane", file_type = "gff")
c(gff_file, gtf_file, gff_file_mouse, genome_file, ens_gff, ens_cdna,
  ath_gff, t2t_gff, t2t_fasta, grch38_gff, mane_gff)

## End(Not run)

Download Any Reference File by URL

Description

Caches a file from an arbitrary URL in the same way as download_reference() (no re-download when present, partial files removed on failure). Useful for annotations without a provider layout, such as the T2T consortium Liftoff files or CHESS releases.

Usage

download_reference_url(
  url,
  output_path = ":cache:",
  file_name = NULL,
  timeout_limit = 3600,
  method = "auto"
)

Arguments

url

URL of the file.

output_path

Directory where the file is saved; ":cache:" (the default) is the package cache.

file_name

File name to use; defaults to the last part of the URL.

timeout_limit

Maximum time in seconds for the download. Takes precedence over options("timeout"). Defaults to 3600.

method

Method used by utils::download.file(). Defaults to "auto".

Value

The full path to the file.

Examples

## Not run: 
liftoff <- download_reference_url(paste0(
  "https://s3-us-west-2.amazonaws.com/human-pangenomics/T2T/CHM13/",
  "assemblies/annotation/chm13v2.0_RefSeq_Liftoff_v5.2.gff3.gz"
))
annot <- prepare_isoformic_annotation(liftoff)
annot

## End(Not run)

Transcript-Type Aware Gene Set Enrichment

Description

Runs gene set enrichment analysis (fgsea::fgseaMultilevel()) separately for transcripts of each type, ranking transcripts by log2 fold-change. Gene sets defined on gene symbols are expanded to all transcripts of their genes, so each transcript category (protein coding, retained intron, nonsense-mediated decay, ...) is tested on its own and in the combined "unproductive" category.

The IsoformicExperiment method uses the stored transcript-level results and the annotation; the data frame method takes a transcript table with transcript_name, transcript_type and log2FC columns plus a tx_to_gene table.

read_gmt() reads gene sets in GMT format into a named list, and plot_enrichment() draws a dot plot of enrichment results.

Usage

run_enrichment(
  self,
  genesets_list,
  tx_to_gene = NULL,
  pval_cutoff = 0.05,
  tx_types = NULL,
  min_size = 15,
  max_size = 500,
  rank_by = c("log2FC", "signed_p", "lfc_z"),
  ...
)

default_enrichment_types(annotation_types = NULL)

read_gmt(path)

plot_enrichment(
  enrichment_df,
  n = 30,
  experiments = NULL,
  nes_cutoff = 0,
  strip_prefix = "^[A-Z]+_",
  label_width = 50
)

Arguments

self

An IsoformicExperiment or a transcript-level DE table.

genesets_list

Named list of character vectors (gene symbols), as returned by read_gmt(), or a named list of such lists (see Collections of gene sets).

tx_to_gene

Data frame with transcript_name and gene_name columns; required by the data frame method, ignored otherwise.

pval_cutoff

Keep pathways with pval at or below this value; NULL keeps all.

tx_types

Named list defining the transcript categories to test. Defaults to default_enrichment_types(), which picks processed_transcript or protein_coding_CDS_not_defined depending on the annotation version.

min_size, max_size

Minimum and maximum gene set size passed to fgsea.

rank_by

Statistic that ranks the transcripts: "log2FC" (default), "signed_p" or "lfc_z" (see Ranking).

...

Passed on to fgsea::fgseaMultilevel(). fgsea runs in the session unless nproc or BPPARAM is given. On Unix-like systems these fork the session: the workers share its memory, but tools that add up the resident memory of the processes count it once per worker. Give the number of workers (nproc = 4); the default of BiocParallel is all the cores of the machine but two, whatever a job scheduler allocated.

annotation_types

Transcript types present in the annotation, used to choose between processed_transcript and protein_coding_CDS_not_defined.

path

Path to a GMT file.

enrichment_df

Result of run_enrichment().

n

Number of top pathways (by adjusted p-value) to show.

experiments

Categories to show; NULL shows all.

nes_cutoff

Minimum absolute NES to show.

strip_prefix

Regular expression removed from pathway names before plotting (default drops MSigDB collection prefixes such as REACTOME_).

label_width

Pathway labels are wrapped to this many characters.

Value

run_enrichment() returns a tibble with the fgsea columns plus experiment (the transcript category), rank_by and, for several collections, collection. read_gmt() returns a named list. plot_enrichment() returns a ggplot object.

Ranking

rank_by chooses the statistic that ranks the transcripts:

  • "log2FC" (default): the log2 fold-change of the stored results, a point estimate that ignores how well it is determined.

  • "signed_p": -log10(pvalue) with the sign of the fold-change, so that the test of the differential expression weighs the ranking. A p-value of zero gets the largest finite value of the table.

  • "lfc_z": the median fold-change over the inferential replicates divided by its standard deviation (lfc_median / lfc_sd of de_confidence()), so that a fold-change the quantification cannot determine ranks low. It needs the confidence table that add_uncertainty(x, group = ) stores, or these two columns in a data frame (the table of de_confidence() works). The ranking has the contrast of that table, the last level of add_uncertainty() against the first; a warning (isoformic_contrast_mismatch) says so when most of its fold-changes have the sign opposite to the stored results. Transcripts that were not assessed, that were collapsed into a group or, for an object, that are not in its differential expression results are not ranked. A fold-change that is the same in every replicate gets the largest finite value of the table.

Collections of gene sets

genesets_list is either one collection (a named list of gene symbol vectors) or several (a named list of such lists, for example list(hallmark = read_gmt(h), reactome = read_gmt(r))). Each collection is tested on its own, so that the adjusted p-values are those of the collection, and the result has a collection column, by which plot_enrichment() splits its panels. Every gene set and every collection needs a name.

Examples

iso <- example_isoformic()
gmt <- system.file("extdata", "reactome_subset.gmt", package = "isoformic")
genesets <- read_gmt(gmt)
length(genesets)

if (requireNamespace("fgsea", quietly = TRUE)) {
  res <- run_enrichment(iso, genesets, pval_cutoff = NULL, min_size = 2)
  head(res)
  plot_enrichment(res, n = 10)
}

Which transcripts can the equivalence classes tell apart?

Description

Salmon summarises the reads as equivalence classes: sets of transcripts with the number of fragments compatible with exactly that set. The abundance of a transcript is determined by these counts only when the classes separate it from the other transcripts. Two isoforms that always appear together in the same classes, for example, can exchange fragments without any change to the class counts.

equivalence_identifiability() reads the classes (⁠salmon quant --dumpEq⁠) and reports, for every transcript, whether it is identifiable from them: whether its abundance is fixed once the total of every class is fixed. This is a property of the classes observed in a sample, not of the posterior draws: a transcript can be non-identifiable and still show a small inferential variance (see Details).

Usage

equivalence_identifiability(
  paths,
  transcripts = NULL,
  ignore_after_bar = TRUE,
  max_dense = 400L,
  max_iterations = 50000L
)

Arguments

paths

Character vector of Salmon output directories (containing quant.sf) or paths to quant.sf files. Names, when present, are the sample IDs; otherwise the directory name is used.

transcripts

Optional transcript IDs to keep. Reading every transcript of a human annotation for many samples takes gigabytes of memory, so add_uncertainty() only reads the expressed ones.

ignore_after_bar

Logical. Keep only the part of transcript names before the first | (GENCODE FASTA headers used as Salmon references).

max_dense

Largest block (number of transcripts) solved with a dense decomposition. Larger blocks use the iterative solver.

max_iterations

Maximum number of iterations of the iterative solver per block. The transcripts of a block that does not converge get NA.

Details

With M the class by transcript membership matrix of one sample, a transcript is identifiable when its unit vector lies in the row space of M, that is, when no vector of the null space of M changes its abundance. The function avoids the decomposition of the full matrix:

  1. A class with a single unresolved transcript resolves it (a class of one transcript does so directly); repeated until nothing changes.

  2. Transcripts that are members of exactly the same classes cannot be told apart: they are marked non-identifiable, replaced by their sum, and step 1 is repeated.

  3. What is left splits into independent blocks. Blocks of up to max_dense transcripts are solved with a singular value decomposition. Larger blocks need the Matrix package: two random vectors are projected on the null space with conjugate gradients, and a transcript with a non-zero coordinate is non-identifiable.

Limits:

  • Only class membership is used, not the conditional probabilities of --dumpEqWeights. Isoforms that share all their fragments have proportional weights, so they stay non-identifiable with the weights; other cases may be resolved by them.

  • The annotation is taken as complete, and the classes are those observed in the sample: a transcript can be identifiable in a deep sample and not in a shallow one. Transcripts without fragments in a sample are not assessed in it.

  • This is not the range of optima of Zheng et al. (2022), which needs their sufficient statistics and a linear program per transcript.

  • Human samples have one block of tens of thousands of transcripts linked by multi-mapping fragments; expect minutes per sample.

In the six GSE129540 samples of the quantification stability article, the estimates of non-identifiable transcripts differed more between two halves of the reads of a sample than those of identifiable transcripts of the same expression: a median absolute log2 ratio of 2.4 against 0.7 at 20 to 100 reads. The posterior draws call three quarters of both kinds uncertain, so the two measures are close to independent.

Value

A tibble with one row per transcript that has fragments in at least one sample: transcript_id, n_samples (samples in which it has fragments and was resolved), n_identifiable (in how many of them it is identifiable), identifiable_fraction and identifiable (TRUE when identifiable in all of them, NA when it was resolved in none).

References

Zheng H, Ma C, Kingsford C (2022). Deriving ranges of optimal estimated transcript expression due to nonidentifiability. Journal of Computational Biology 29:121-139. doi:10.1089/cmb.2021.0444

See Also

equivalence_support() for the share of unique fragments, add_uncertainty() for the uncertainty measured by the posterior draws.

Examples

# Two transcripts that always share their classes, and one with its own
dir <- file.path(tempdir(), "identifiability_example")
dir.create(file.path(dir, "aux_info"), recursive = TRUE, showWarnings = FALSE)
writeLines(
  c("3", "2", "tx1", "tx2", "tx3", "2\t0\t1\t10", "1\t2\t5"),
  file.path(dir, "aux_info", "eq_classes.txt")
)
equivalence_identifiability(c(sample1 = dir))

Example IsoformicExperiment

Description

Loads a small IsoformicExperiment bundled with the package: transcript abundances (TPM) for the isoforms of a handful of genes from a preeclampsia placenta RNA-seq study (25 samples), GENCODE v33 annotation for those genes, and transcript- and gene-level differential expression results. It is used throughout the documentation and is suitable for trying every method of the class in well under a second.

Usage

example_isoformic()

Value

An IsoformicExperiment.

Examples

iso <- example_isoformic()
iso

Frozen Reference Datasets

Description

isoformic ships evidence tables derived from public resources, frozen at a given version so that results are reproducible:

  • appris: APPRIS principal/alternative isoform labels and method scores (functional residues, structure, conservation, domains) per transcript, from the APPRIS release files.

  • appris_domains: Pfam domain genomic coordinates per transcript (APPRIS SPADE).

  • riboseq_orfs: GENCODE Ribo-seq ORF catalog, phase 1 and phase 2, with exon blocks and compatible transcripts.

  • nmd_exons: NMD-inducing cassette exons validated by NMD inhibition and nanopore sequencing (Karousis et al. 2021, Genome Biology, Supplementary Table 1).

  • polyasite: PolyASite 2.0 poly(A) site atlas (GRCh38) with site class and poly(A) signals.

  • gtex_transcript_tpm: GTEx v8 median transcript TPM per tissue (RSEM).

frozen_datasets() lists them with version, source URLs and the MD5 of the frozen file. fetch_frozen_data() returns the local path of a dataset, downloading the frozen file from the first mirror that has it (frozen_mirrors(): any URL in options(isoformic.frozen_mirrors = ), the package's GitHub release, then the Zenodo snapshot of the processed files) or, when that is not possible (build = "auto") or asked for (build = "always"), rebuilding it from the source files with the matching ⁠build_frozen_*()⁠ function. read_frozen_data() fetches and reads it. bundle_frozen_data() assembles the snapshot that is deposited on Zenodo: every frozen file, the coding potential model, an MD5SUMS file and a README stating versions and sources.

Usage

frozen_datasets()

frozen_mirrors(
  release_tag = "frozen-data",
  zenodo_record = frozen_zenodo_record()
)

fetch_frozen_data(
  name,
  output_path = ":cache:",
  build = c("auto", "never", "always"),
  verify = TRUE,
  release_tag = "frozen-data",
  mirrors = frozen_mirrors(release_tag),
  ...
)

read_frozen_data(
  name,
  output_path = ":cache:",
  build = c("auto", "never", "always"),
  ...
)

bundle_frozen_data(
  output_dir,
  output_path = ":cache:",
  build = c("auto", "never", "always"),
  include_coding_model = TRUE,
  verify = TRUE
)

Arguments

release_tag

Tag of the GitHub release hosting the frozen files.

zenodo_record

Zenodo record id (or ⁠https://zenodo.org/records/<id>⁠ URL) of a deposit holding the frozen files; defaults to the record published with the package, NA when there is none.

name

Dataset name, one of names(frozen_datasets()).

output_path

Directory holding the frozen files; ":cache:" (default) uses get_isoformic_cache("frozen").

build

"auto" (download, else build from sources), "never" or "always".

verify

Logical, check the MD5 of the file against the registry (default TRUE; a mismatch is a warning, since a rebuilt file from a newer source is still usable).

mirrors

Character vector of base URLs tried in order for the frozen file; default frozen_mirrors().

...

Reserved for future use; must be empty.

output_dir

Directory receiving the bundle (created if needed).

include_coding_model

Logical, also copy the coding potential model files (default TRUE).

Value

frozen_datasets() returns a tibble; fetch_frozen_data() the file path, invisibly; read_frozen_data() a tibble; frozen_mirrors() a character vector; bundle_frozen_data() the bundle directory, invisibly.

Examples

frozen_datasets()[, c("name", "version", "file")]
## Not run: 
appris <- read_frozen_data("appris")
head(appris)

## End(Not run)

Retrieve System-Dependent Cache Path for Isoformic

Description

Determines the appropriate user cache directory for the isoformic package based on the operating system. On macOS, it avoids using paths with spaces and follows the XDG base directory specification.

Usage

get_isoformic_cache(..., ext = NULL)

Arguments

...

Additional path components to append to the cache directory.

ext

An optional file extension (e.g., "rds", "csv") to append to the final path.

Details

This function uses the ⁠[tools::R_user_dir()]⁠ function to determine the user cache directory.

Value

A path character string representing the path to the user cache directory for the isoformic package.


Tissue Reference Values from GTEx

Description

Computes, from the GTEx v8 median transcript TPM of one tissue (frozen dataset gtex_transcript_tpm, frozen_data) and the productivity calls of x, the reference state of every gene in healthy tissue: its productive fraction, its dominant isoform and the dominant isoform's productivity. productive_fraction() accepts the result (or a tissue name) as reference and reports the difference between the samples and the tissue baseline, which separates a disease-specific loss of productive isoforms from a tissue's normal state.

Transcript identifiers are matched without version; GTEx v8 uses GENCODE v26, so transcripts annotated later have no reference value.

Usage

gtex_reference(self, tissue, gtex = NULL, include_altered = TRUE, ...)

gtex_tissues(gtex = NULL)

Arguments

self

An IsoformicExperiment.

tissue

GTEx tissue name (SMTSD, for example "Whole Blood", "Brain - Cortex"); see gtex_tissues().

gtex

Data frame or Parquet path of the GTEx table; NULL fetches the frozen dataset.

include_altered

Logical, count altered_productive isoforms as productive (default TRUE).

...

Passed on to methods.

Value

A tibble with one row per gene of x: reference_tissue, reference_gene_tpm, reference_productive_fraction, reference_dominant_transcript_id, reference_dominant_productivity, n_reference_transcripts.

Examples

## Not run: 
iso <- example_isoformic()
ref <- gtex_reference(iso, tissue = "Whole Blood")
productive_fraction(iso, group = "condition", reference = ref)

## End(Not run)

Read the inferential uncertainty that Salmon writes

Description

Salmon quantifies how well each transcript abundance is determined by the reads, and writes that information next to quant.sf:

  • read_inferential_replicates() reads the Gibbs (--numGibbsSamples) or bootstrap (--numBootstraps) replicates from ⁠aux_info/bootstrap/⁠ (the format is identical in Salmon 1.x and in the Rust rewrite, Salmon 2). It returns a list with one transcript x sample matrix of counts per replicate, the layout used by productive_fraction() and add_uncertainty().

  • equivalence_support() reads the equivalence classes (--dumpEq, aux_info/eq_classes.txt.gz) and reports, for every transcript, how many of its fragments are compatible with no other transcript.

  • salmon_run_qc() reads aux_info/meta_info.json and reports the mapping rate, the library type, whether the optimiser converged and how many replicates were drawn.

  • inferential_replicates_table() and as_inferential_replicates() convert the list of replicates to and from a long table (one row per transcript, sample and replicate), which can be stored as Parquet.

Usage

read_inferential_replicates(
  paths,
  transcripts = NULL,
  n_draws = NULL,
  ignore_after_bar = TRUE
)

equivalence_support(paths, transcripts = NULL, ignore_after_bar = TRUE)

salmon_run_qc(paths, min_percent_mapped = 50)

inferential_replicates_table(reps)

as_inferential_replicates(table, samp_type = "gibbs")

Arguments

paths

Character vector of Salmon output directories (containing quant.sf) or paths to quant.sf files. Names, when present, are the sample IDs; otherwise the directory name is used.

transcripts

Optional transcript IDs to keep. Reading every transcript of a human annotation for many samples takes gigabytes of memory, so add_uncertainty() only reads the expressed ones.

n_draws

Number of replicates to keep (the first ones). NULL keeps all of them.

ignore_after_bar

Logical. Keep only the part of transcript names before the first | (GENCODE FASTA headers used as Salmon references).

min_percent_mapped

Samples below this mapping rate (percent) get the low_mapping_rate flag in salmon_run_qc().

reps

A list of transcript x sample count matrices, one per replicate.

table

A long table with transcript_id, sample_id, draw and count columns, as returned by inferential_replicates_table().

samp_type

Replicate type recorded on the result, "gibbs" or "bootstrap".

Value

  • read_inferential_replicates(): a list of numeric matrices (transcripts by samples, counts) with the replicate type ("gibbs" or "bootstrap") in the samp_type attribute.

  • inferential_replicates_table(): a tibble with transcript_id, sample_id, draw and count. as_inferential_replicates() is its inverse.

  • equivalence_support(): a tibble with one row per transcript: transcript_id, n_classes (mean number of equivalence classes per sample), n_fragments and n_unique_fragments (summed over samples), unique_fraction (share of the fragments of the transcript that map to it alone) and n_samples.

  • salmon_run_qc(): a tibble with one row per sample.

Examples

quant_dirs <- list.files(
  system.file("extdata", "mini_quants", package = "isoformic"),
  full.names = TRUE
)
names(quant_dirs) <- sub("_quant$", "", basename(quant_dirs))
# The bundled quantifications were made without replicates
salmon_run_qc(quant_dirs)[, c("sample_id", "percent_mapped", "qc_flag")]

Put the quantification uncertainty into the counts

Description

Reads that map to several isoforms make the counts of an isoform more variable than a Poisson count, by an amount that differs between transcripts. Baldoni et al. (2024) estimate this overdispersion for every transcript from the Salmon replicates and divide it out of the counts, so that tests built for counts (edgeR, limma, DESeq2) keep their error rate without a model of their own for the read ambiguity.

  • inferential_overdispersion() computes the overdispersion of every transcript from the replicates stored in the object, as edgeR::catchSalmon() does: the Pearson statistic of a quasi-Poisson fit to the replicates of each sample, pooled over the samples, moderated towards the median with a prior of prior_df degrees of freedom and floored at one. The estimates use the transcripts whose replicates are in the object (those with a mean count of at least min_count in add_uncertainty()), so the prior differs from the one catchSalmon() computes over every transcript of the index; transcripts without replicates get the prior.

  • scale_counts() divides an assay by the overdispersion and stores the result as a new assay, ready for a count-based test.

The overdispersion complements the confidence classes of de_confidence(): it changes the test, while the classes describe how far each call can be trusted.

Usage

inferential_overdispersion(self, prior_df = 3, ...)

scale_counts(self, assay = "counts", name = paste0(assay, "_scaled"), ...)

Arguments

self

An IsoformicExperiment with inferential replicates (see add_uncertainty()).

prior_df

Degrees of freedom of the prior (3 in edgeR).

...

Unused.

assay

Name of the counts assay to scale.

name

Name of the new assay.

Value

inferential_overdispersion(): a tibble with transcript_id, overdispersion and df (degrees of freedom of the estimate), with the prior in the prior attribute. scale_counts(): the object with the scaled assay added.

References

Baldoni PL, Chen Y, Hediyeh-Zadeh S, Liao Y, Dong X, Ritchie ME, Shi W, Smyth GK (2024). Dividing out quantification uncertainty allows efficient assessment of differential transcript expression with edgeR. Nucleic Acids Research 52(3):e13.

See Also

add_uncertainty(), de_confidence()

Examples

extdata <- system.file("extdata", package = "isoformic")
quant_dirs <- list.files(file.path(extdata, "mini_quants"), full.names = TRUE)
names(quant_dirs) <- sub("_quant$", "", basename(quant_dirs))
iso <- read_salmon(
  quant_dirs,
  annot_path = file.path(extdata, "mini_annotation"),
  col_data = data.frame(
    sample_id = names(quant_dirs),
    condition = rep(c("control", "treatment"), each = 3)
  )
)
iso@metadata$inf_reps <- as_inferential_replicates(read_parquet(
  file.path(extdata, "mini_draws.parquet")
))
iso <- scale_counts(iso)
assay_names(iso)
head(inferential_overdispersion(iso))

Flag Transcripts Whose Gene Is Differentially Expressed

Description

Table-based helper adding a DEG_sig column ("YES"/"NO") to a transcript table. Row order is preserved. With an IsoformicExperiment, isoform_switches() relates transcript and gene significance directly.

Usage

is_deg_sig(deg_sig_vector, det_table)

Arguments

deg_sig_vector

Character vector of transcript names (or IDs) belonging to significantly differentially expressed genes.

det_table

Transcript-level table with a transcript_name (or transcript_id) column.

Value

det_table with an extra DEG_sig column.

Examples

det_table <- data.frame(
  transcript_name = c("tx1", "tx2", "tx3"),
  log2FC = c(2.5, -1.2, 0.8)
)
is_deg_sig(c("tx1", "tx3"), det_table)

Convert Between IsoformicExperiment and SummarizedExperiment

Description

as_isoformic() builds an IsoformicExperiment from a SummarizedExperiment (for example the output of tximeta), from a tximport list (abundance, counts, length) or from a named list of matrices. as_summarized_experiment() does the reverse at the transcript or gene level, which is convenient for running Bioconductor tools such as DESeq2 or fishpond on the stored assays (a counts assay is placed first, as those tools expect).

Usage

as_isoformic(
  x,
  annot_path,
  col_data = NULL,
  experiment_name = NULL,
  ignore_after_bar = TRUE,
  drop_unannotated = FALSE
)

as_summarized_experiment(self, level = c("transcript", "gene"), ...)

Arguments

x

A SummarizedExperiment, a tximport list or a named list of matrices.

annot_path

Annotation directory or GFF3/GTF file.

col_data

Sample metadata; taken from colData(x) when x is a SummarizedExperiment.

experiment_name

Optional experiment name.

ignore_after_bar

Logical, truncate GENCODE |-separated transcript IDs.

drop_unannotated

Logical, drop transcripts absent from the annotation instead of failing.

self

An IsoformicExperiment.

level

"transcript" (default) or "gene".

...

Passed on to methods.

Value

as_isoformic() returns an IsoformicExperiment; as_summarized_experiment() returns a SummarizedExperiment.

Examples

iso <- example_isoformic()
txi <- list(abundance = assay(iso, "abundance"), counts = assay(iso, "counts"))
annot <- system.file("extdata", "example_experiment", "annotation", package = "isoformic")
iso2 <- as_isoformic(txi, annot_path = annot, col_data = col_data(iso))
iso2

if (requireNamespace("SummarizedExperiment", quietly = TRUE)) {
  se <- as_summarized_experiment(iso, level = "gene")
  se
}

Save and Restore IsoformicExperiment Objects as Parquet

Description

write_isoformic() writes an IsoformicExperiment to a directory of Parquet files and read_isoformic() restores it. The layout is:

<path>/
  experiment.parquet        key/value: experiment_name, annot_path, ...
  col_data.parquet          sample metadata
  metadata.parquet          key/value: scalar entries of `metadata`
  tx_type_palette.parquet   transcript_type, color
  assays/<name>.parquet     transcript_id + one column per sample
  gene_assays/<name>.parquet  only explicitly set gene assays
  dea/det.parquet, dea/deg.parquet, dea/cutoffs.parquet
  gsea/<name>.parquet
  annotation/               copy of the annotation directory (optional)

With copy_annotation = TRUE the annotation directory is copied inside the experiment directory so that the result is self-contained and portable. Otherwise annot_path is stored as an absolute path and must still exist when the object is read back (it can be overridden with the annot_path argument of read_isoformic()).

Usage

write_isoformic(
  self,
  path = NULL,
  overwrite = FALSE,
  copy_annotation = FALSE,
  ...
)

read_isoformic(path, annot_path = NULL)

Arguments

self

An IsoformicExperiment.

path

Directory to write to or read from. For write_isoformic() defaults to the object's data_path, or to get_isoformic_cache("experiments", experiment_name).

overwrite

Logical, replace an existing directory.

copy_annotation

Logical, copy the annotation directory inside path.

...

Passed on to methods.

annot_path

Optional annotation directory overriding the stored one when reading.

Value

write_isoformic() returns the object with data_path set, invisibly. read_isoformic() returns an IsoformicExperiment.

Examples

iso <- example_isoformic()
dir <- file.path(tempdir(), "iso_example")
iso <- write_isoformic(iso, dir, overwrite = TRUE, copy_annotation = TRUE)
list.files(dir, recursive = TRUE)
iso2 <- read_isoformic(dir)
identical(assay(iso), assay(iso2))

Options and environment variables used by isoformic

Description

isoformic has two package options, isoformic.frozen_mirrors and isoformic.orf_cache, and is otherwise configured through base R options, the environment variables that locate the user cache and the settings of the packages it builds on. This page lists every setting the package reads or is affected by, what it changes and where it is used. Settings are read at call time, so they can be changed with options() / Sys.setenv() in a session, scoped with withr::with_options() / withr::with_envvar(), or placed in .Rprofile / .Renviron.

Package options

isoformic.frozen_mirrors

Character vector of base URLs tried first by fetch_frozen_data() (and every function that loads a frozen dataset, such as add_appris() or polya_sites(polya_atlas = "polyasite")) before the frozen-data GitHub release and the Zenodo record returned by frozen_mirrors(). Each URL is joined with the file name of the dataset, for example options(isoformic.frozen_mirrors = "https://zenodo.org/records/<id>/files/") pins an analysis to one Zenodo deposit, and "file:///data/isoformic-frozen/" serves the files from a local or institutional mirror. The MD5 recorded in frozen_datasets() is verified whatever the mirror. Default: unset (no extra mirror).

isoformic.orf_cache

FALSE stops transcript_orfs() from reading and writing annot_data_orfs.parquet, the table of the ORFs computed so far that it keeps in the annotation directory. The ORFs are then computed in every session. Default: unset (TRUE).

Base R options

timeout

Timeout in seconds of utils::download.file() and url() connections. download_reference(), download_reference_url(), download_hprc_annotation(), download_fantom_cat_tables(), fetch_frozen_data() and the builders in build_frozen_data raise it, for the duration of the download only, to at least the timeout_limit of the call (3600 seconds by default, large reference files are several gigabytes) and never lower it. Set a larger value for slow connections.

download.file.method, download.file.extra

Define what the method = "auto" default of the download functions resolves to and the extra command line flags of the "wget" and "curl" methods. Pass method explicitly to override them for one call.

rlang_interactive

Overrides interactive() for rlang::is_interactive(). In a non-interactive session the download progress is silenced (quiet = TRUE in utils::download.file()) and missing optional packages (fgsea, condathis, readxl, SummarizedExperiment) raise an error instead of an installation prompt.

cli.num_colors, cli.unicode, cli.default_handler, cli.width, cli.progress_show_after

Rendering of every message, warning and error, which the package emits through the cli package. cli.unicode = FALSE and cli.num_colors = 1 produce plain ASCII output for logs; see ?cli::cli-config.

Environment variables

R_USER_CACHE_DIR, XDG_CACHE_HOME

Root of the user cache. get_isoformic_cache() resolves tools::R_user_dir("isoformic", "cache"), which honours R_USER_CACHE_DIR first, then XDG_CACHE_HOME (⁠~/.cache⁠ by default on Linux). On macOS the package sets XDG_CACHE_HOME to ⁠~/.cache⁠ for the lookup when it is unset, so the cache lives in ⁠~/.cache/R/isoformic/⁠ instead of ⁠~/Library/Caches/org.R-project.R/R/isoformic/⁠ and never contains a space. The cache holds downloaded references (download_reference()), the frozen datasets (⁠frozen/⁠), their sources (⁠sources/<name>/⁠) and the Zenodo bundle (⁠zenodo_deposit/⁠). Point it to a shared or scratch disk on HPC systems.

LOCALAPPDATA

On Windows, the root that tools::R_user_dir() uses when R_USER_CACHE_DIR is unset.

HOME, USERPROFILE

Define the ~ that the defaults above and fs::path_home() expand to.

http_proxy, https_proxy, ftp_proxy, no_proxy

Proxy settings honoured by utils::download.file() and url() (libcurl and internal methods) and therefore by every download in the package, including the connectivity check curl::has_internet().

CURL_CA_BUNDLE, SSL_CERT_FILE

Certificate bundle used by the libcurl download method, needed behind TLS-intercepting proxies.

Settings of other packages

DuckDB

Every Parquet read and write (read_parquet(), write_parquet(), read_tabular()) and the heavy joins run in a short-lived in-memory DuckDB connection with the DuckDB defaults: all CPU cores (threads) and 80% of the RAM as memory_limit. The package does not expose these; they are DuckDB session settings and the connections are not shared with user code. Extensions, secrets and the files of a query that spills to disk go to ⁠isoformic-duckdb/⁠ under tempdir(), unless the duckdb.home option or the DUCKDB_R_HOME environment variable is set: DuckDB then uses its own locations under that directory.

condathis.micromamba_path, CONDATHIS_MICROMAMBA_PATH, CONDA_PREFIX, XDG_DATA_HOME

Read by the condathis package, which salmon_index() and salmon_quant() use to run salmon in a micromamba environment: where the micromamba binary is found and where environments are created. See ?condathis::condathis.

⁠BIOCONDUCTOR_*⁠, ⁠R_LIBS*⁠

Only relevant for installing the optional packages (fgsea, SummarizedExperiment); the package itself does not read them.

Development and test settings

These are not read by the package code but control its test suite and checks (see justfile):

ISOFORMIC_FULL

"true" runs the tests and articles that download references or run external tools (⁠just test-full⁠, ⁠just render-articles-full⁠). Unset by default: the tests, examples and site then use only the data bundled with the package.

TESTTHAT_CPUS

Number of parallel testthat workers used by ⁠just test⁠.

NOT_CRAN

Set to "true" by devtools::test(); tests that need optional packages use testthat::skip_if_not_installed() rather than network access, so no test downloads data.

⁠_R_CHECK_SYSTEM_CLOCK_⁠

Set to "0" by ⁠just check⁠ to skip the clock check of ⁠R CMD check --as-cran⁠.

HOME, R_USER_CACHE_DIR, XDG_CACHE_HOME, R_USER_DATA_DIR, XDG_DATA_HOME, LOCALAPPDATA, APPDATA

The test setup redirects all of them to temporary directories so that tests never touch the user cache.

See Also

get_isoformic_cache(), frozen_data, download_reference()

Examples

# Pin the frozen datasets to one Zenodo deposit for a reproducible run
withr::with_options(
  list(isoformic.frozen_mirrors = "https://zenodo.org/records/1234567/files/"),
  frozen_mirrors()
)

# Where the cache is, and how to move it
get_isoformic_cache()
withr::with_envvar(
  list(R_USER_CACHE_DIR = tempdir()),
  get_isoformic_cache("frozen")
)

IsoformicExperiment: Transcript, Gene and Exon Level Data in One Object

Description

IsoformicExperiment is an S7 class modelled after SummarizedExperiment, but organised around transcriptomic diversity: the same samples are described at three levels that are kept consistent by construction.

  • Transcript level: assays are numeric matrices with transcript IDs as row names and sample IDs as column names (for example abundance, counts, length). All assays share the same dimnames.

  • Gene level: gene assays are derived from the transcript assays by summing the isoforms of each gene (abundance-weighted means for length), cached, and can be overridden with gene_assays<-.

  • Exon level: exon structures come from the annotation and are available through annot_data_exons(), exon_table() and exon_diversity().

Annotation is never copied into the object. The annot_path property points to an annotation directory of Parquet files created by prepare_isoformic_annotation() (a GFF3/GTF file is accepted and converted on the fly). Tables are read with DuckDB on first access and cached in memory keyed by file path, size and modification time, so a re-created annotation is picked up automatically and several objects sharing one annotation share one copy of the tables.

Derived results (gene assays, row data, isoform fractions) are cached per object in the .cache environment, keyed by a hash of their inputs, and therefore survive copies but never go stale. See clear_cache().

Objects persist to disk as a directory of Parquet files with write_isoformic() and are restored with read_isoformic().

Usage

IsoformicExperiment(
  experiment_name = NULL,
  annot_path = NULL,
  assays = list(),
  col_data = NULL,
  gene_assays = list(),
  dea = list(),
  gsea = list(),
  metadata = list(),
  data_path = NULL,
  tx_type_palette = NULL
)

Arguments

experiment_name

Single string naming the experiment.

annot_path

Annotation directory or GFF3/GTF file.

assays

Named list of transcript-level matrices (or data frames with a transcript_id column).

col_data

Data frame of sample metadata with a sample_id column (or sample IDs as row names / first column).

gene_assays

Optional named list of gene-level matrices.

dea

Optional list of differential expression results.

gsea

Optional named list of enrichment results.

metadata

Optional named list of free-form metadata.

data_path

Optional on-disk location of the experiment.

tx_type_palette

Optional named colour vector per transcript type.

Value

An IsoformicExperiment object.

Properties

experiment_name

Single string. Generated when not supplied.

annot_path

Path to the annotation directory, or NULL for an empty object.

data_path

Directory the object was written to or read from (see write_isoformic()), or NULL.

assays

Named list of transcript-level matrices.

gene_assays

Named list of gene-level matrices. Derived from assays when not set explicitly.

col_data

Tibble of sample metadata; its sample_id column matches the assay column names.

dea

List with differential expression results: det (transcripts), deg (genes) and cutoffs. Use de_tx<- and de_gene<- to set them.

gsea

Named list of enrichment result tables.

metadata

Free-form named list.

annot_metadata

Named list describing the annotation source, read from the annotation directory unless set explicitly.

tx_type_palette

Named character vector of colours per transcript type, used by all plots. Defaults to tx_type_palette().

annot_data_transcripts, annot_data_genes, annot_data_exons

Read-only, cached annotation tables.

Subsetting

x[i, j] keeps the transcripts i and the samples j, given as IDs, positions or logical vectors, and at least one of each. Everything stored by transcript or by sample follows: the assays, the sample table, stored gene assays (the genes of the kept transcripts) and the inferential replicates in metadata(x)$inf_reps. The uncertainty tables of add_uncertainty() are restricted to the kept transcripts (a collapsed ambiguity group stays only with all its members); when samples are dropped they are not recomputed, and a message says so. Differential expression and enrichment results are kept as they are.

A subset holds its own copy of the inferential replicates of the kept transcripts and samples. To compare two groups of a larger object, pass levels to the function instead of subsetting: the samples of the other groups are ignored and nothing is copied. A subset with other transcripts starts with an empty cache of derived tables.

See Also

example_isoformic() for a ready-made object, read_salmon() and as_isoformic() to create one from quantifications, IsoformicExperiment-accessors for the accessor generics.

Examples

iso <- example_isoformic()
iso
dim(iso)
assay_names(iso)
head(row_data(iso))
head(gene_assay(iso, "abundance"))

# Subset like a SummarizedExperiment. Stored gene assays, inferential
# replicates and uncertainty tables follow the transcripts and samples kept
iso[1:10, c("SRR11498039", "SRR11498063")]

# Build one from matrices
annot <- system.file("extdata", "example_experiment", "annotation", package = "isoformic")
tpm <- assay(iso, "abundance")[1:5, 1:3]
small <- IsoformicExperiment(
  experiment_name = "tiny",
  annot_path = annot,
  assays = list(abundance = tpm),
  col_data = data.frame(sample_id = colnames(tpm), condition = c("a", "a", "b"))
)
small

Accessors for IsoformicExperiment Objects

Description

S7 generics giving SummarizedExperiment-style access to the three levels of an IsoformicExperiment. All of them return in-memory tibbles or matrices; the annotation tables are read from Parquet on first use and cached (see the class documentation).

Samples

  • col_data(), ⁠col_data<-⁠: sample metadata (sample_id first).

  • col_names(): sample IDs of the assays.

Transcript level

  • assays(), assay(x, name), assay_names(), ⁠assay<-⁠: transcript matrices. assay() without a name returns the first assay.

  • row_names(): transcript IDs of the assays.

  • row_data(): transcript annotation (with gene columns) for the assayed transcripts, in assay row order.

  • tx_annot(): the same join for all annotated transcripts.

  • tx_to_gene(): two-column transcript/gene mapping.

Gene level

  • gene_assays(), gene_assay(x, name), ⁠gene_assays<-⁠: gene matrices, derived by summing isoforms unless set explicitly.

  • gene_data(): gene annotation for the genes represented in the assays.

  • gene_names(): gene IDs of the gene assays.

Annotation

  • annot_data_transcripts(), annot_data_genes(), annot_data_exons(): the raw annotation tables.

  • annot_data(): transcript-centric join of transcripts and genes (exons optional).

  • annot_metadata(): named list describing the annotation source.

  • exon_table(x, gene_name): exons of the transcripts of selected genes.

Housekeeping

  • clear_cache(): drop cached derived data for the object (and, with annotation = TRUE, the shared annotation tables).

Usage

col_data(self, ...)

col_data(self) <- value

col_names(self, ...)

assays(self, ...)

assay_names(self, ...)

assay(self, name = NULL, ...)

assay(self, name) <- value

row_names(self, ...)

row_data(self, ...)

tx_annot(self, ...)

tx_to_gene(self, ...)

gene_assays(self, ...)

gene_assays(self) <- value

gene_assay(self, name = NULL, ...)

gene_names(self, ...)

gene_data(self, ...)

annot_data_transcripts(self, ...)

annot_data_genes(self, ...)

annot_data_exons(self, ...)

annot_data(self, with_exons = FALSE, ...)

annot_metadata(self, ...)

exon_table(self, gene_name, ...)

clear_cache(self, annotation = FALSE, ...)

Arguments

self

An IsoformicExperiment.

...

Passed on to methods.

value

Replacement value.

name

Name of the assay. NULL selects the first assay.

with_exons

Logical, also join the exon table (one row per exon).

gene_name

Character vector of gene names or gene IDs.

annotation

Logical, also clear the shared annotation cache.

Value

See the individual descriptions above.

Examples

iso <- example_isoformic()
col_data(iso)
assay_names(iso)
assay(iso, "abundance")[1:3, 1:3]
gene_assay(iso, "abundance")[1:3, 1:3]
head(row_data(iso))
head(gene_data(iso))
head(exon_table(iso, "RBPJ"))

Merge Gene and Transcript Level Differential Expression Tables

Description

Table-based helper combining gene-level and transcript-level results into the long format used by plot_log2fc(). With an IsoformicExperiment, de_table() produces the same table from the stored results.

Usage

join_DEG_DET(
  deg_table,
  det_table,
  logfc_cut = 1,
  pval_cut = 0.05,
  use_fdr = FALSE,
  transcript_types = default_transcript_types()
)

Arguments

deg_table

Gene-level results with gene_id, gene_name, log2FC and pvalue columns.

det_table

Transcript-level results with transcript_id, transcript_name, transcript_type, log2FC and pvalue columns.

logfc_cut

Absolute log2 fold-change cutoff for significance.

pval_cut

P-value cutoff for significance. Like the cutoffs of de_tx(), a feature is significant when abs(log2FC) >= logfc_cut and the p-value is ⁠<= pval_cut⁠.

use_fdr

Logical, test the qvalue column instead of pvalue (when present), as the stored cutoffs of an IsoformicExperiment do.

transcript_types

Transcript types to keep. NULL keeps all.

Value

A tibble with feature_id, feature_name, feature_type, gene_name, log2FC, pvalue (and qvalue when present) and is_de.

Examples

deg_table <- data.frame(
  gene_id = c("gene1", "gene2"),
  gene_name = c("GeneA", "GeneB"),
  log2FC = c(1.5, -2.0),
  pvalue = c(0.01, 0.04)
)
det_table <- data.frame(
  transcript_id = c("tx1", "tx2", "tx3"),
  transcript_name = c("Transcript1", "Transcript2", "Transcript3"),
  transcript_type = c("protein_coding", "lncRNA", "processed_transcript"),
  gene_name = c("GeneA", "GeneA", "GeneB"),
  log2FC = c(1.2, -1.8, 0.5),
  pvalue = c(0.02, 0.03, 0.2)
)
join_DEG_DET(deg_table, det_table, logfc_cut = 1, pval_cut = 0.05)

Create a Transcript-to-Gene Mapping Table

Description

Builds a transcript-to-gene table from a GENCODE transcriptome FASTA file (parsing the |-separated headers) or from a GFF3/GTF annotation (through prepare_isoformic_annotation()). Parsing is done by DuckDB, so a full GENCODE FASTA (about 250,000 headers, gzip-compressed) takes a couple of seconds.

Usage

make_tx_to_gene(
  file_path,
  file_type = c("auto", "fasta", "gff", "gtf"),
  output_path = NULL
)

Arguments

file_path

Path to a FASTA (.fa, .fasta, optionally .gz), GFF3 or GTF file, or to an annotation directory.

file_type

"auto" (default) detects the format from the file extension; otherwise one of "fasta", "gff", "gtf".

output_path

Passed to prepare_isoformic_annotation() for GFF3/GTF inputs.

Details

With an IsoformicExperiment object, use tx_to_gene() or tx_annot(), which read the same information from the annotation directory.

Value

A tibble with columns transcript_id, gene_id, havana_gene_id, havana_transcript_id, transcript_name, gene_name, tx_length and transcript_type. The Havana columns are NA for GFF3/GTF inputs.

Examples

gff <- system.file("extdata", "example.gff3", package = "isoformic")
tx2gene <- make_tx_to_gene(gff, output_path = tempdir())
head(tx2gene)

Merge Per-Haplotype Annotations Into One Annotation Directory

Description

Phased (trio-binned or pangenome) assemblies come with one annotation per haplotype, for example the HPRC CAT files HG00438.1.chm13.gff3.gz and HG00438.2.chm13.gff3.gz. merge_annotations() converts each file (or reuses an existing annotation directory), tags every table with the haplotype label, makes identifiers unique by appending ⁠_<haplotype>⁠, and writes one combined annotation directory. Transcript, gene and exon IDs therefore become ⁠<id>_<haplotype>⁠, the convention expected for the row names of a haplotype-resolved IsoformicExperiment (rename the sequences of the per-haplotype transcript FASTA files the same way before building the Salmon index).

The source_gene_id / source_transcript_id columns (GRCh38 identifiers kept by Liftoff/CAT) are left untouched, which is what haplotype_summary() uses to compare haplotypes of the same gene.

Usage

merge_annotations(
  annot_paths,
  output_path = NULL,
  annot_name = "merged_haplotypes",
  id_suffix = TRUE,
  overwrite = FALSE
)

Arguments

annot_paths

Named character vector: names are haplotype labels, values are GFF3/GTF files or annotation directories.

output_path

Directory under which the merged annotation directory is created. NULL uses get_isoformic_cache().

annot_name

Name of the merged annotation directory.

id_suffix

Logical. Append ⁠_<haplotype>⁠ to gene, transcript and exon identifiers (default TRUE). Set to FALSE when the identifiers are already unique across haplotypes.

overwrite

Logical. Replace an existing merged directory.

Value

The path to the merged annotation directory.

Examples

gff <- system.file("extdata", "example.gff3", package = "isoformic")
merged <- merge_annotations(
  c(hap1 = gff, hap2 = gff),
  output_path = tempdir(),
  annot_name = "example_diploid",
  overwrite = TRUE
)
tx <- read_parquet(file.path(merged, "annot_data_transcripts.parquet"))
table(tx$haplotype)
head(tx$transcript_id)

Read and Write Parquet Files

Description

Thin, dependency-light wrappers around DuckDB for reading tabular files into tibbles and for writing data frames as Parquet. These are the readers used throughout isoformic: annotation tables, experiment caches and the bundled example data are all stored as Parquet.

Usage

read_parquet(path, columns = NULL, n_max = Inf, ...)

read_tabular(path, columns = NULL, n_max = Inf, ...)

write_parquet(
  x,
  path,
  compression = c("zstd", "snappy", "gzip", "uncompressed"),
  ...
)

Arguments

path

Path to the file to read or write.

columns

Optional character vector of columns to read. NULL reads all columns.

n_max

Maximum number of rows to read. Inf (default) reads all.

...

Reserved for future use; must be empty.

x

A data frame (or tibble) to write.

compression

Parquet compression codec.

Details

read_parquet() reads a Parquet file. read_tabular() reads Parquet, CSV or TSV files (.csv, .tsv, .tab, .txt, Salmon .sf; optionally gzip-compressed), auto-detecting delimiter and types. write_parquet() writes any data frame to a Parquet file, creating parent directories as needed.

Factor columns are stored as Parquet strings and come back as character. Row names are not stored; keep identifiers in a regular column.

Value

read_parquet() and read_tabular() return a tibble. write_parquet() returns path, invisibly.

Examples

tmp <- tempfile(fileext = ".parquet")
write_parquet(data.frame(id = c("a", "b"), value = c(1.5, 2)), tmp)
read_parquet(tmp)
read_parquet(tmp, columns = "id", n_max = 1)
read_tabular(tmp)

Plot the Genomic Context of a Gene's Isoforms

Description

Draws the exon-intron structure of every annotated transcript of one or more genes along the genome, one row per transcript, coloured by transcript type, with introns as lines carrying strand arrows. This is a pure ggplot2 implementation reading the exon table of the annotation directory, so it needs no genome packages. The IsoformicExperiment method can annotate each transcript with its mean expression and highlight differentially expressed isoforms.

The data frame method takes an exon table as returned by exon_table() or prepare_exon_annotation() (columns transcript_id, start_pos, end_pos, and optionally transcript_name, transcript_type, gene_name, seqid, strand). plot_tx_context() is kept as an alias of that method accepting the legacy column names tx_id, exon_left and exon_right.

Usage

plot_genomic_context(
  self,
  gene_name = NULL,
  assay = "abundance",
  highlight_de = TRUE,
  color_palette = NULL,
  expression = NULL,
  highlight = NULL,
  highlight_poison_exons = TRUE,
  upstream_offset = 0,
  downstream_offset = 0,
  exon_height = 0.6,
  ncol = 1L,
  ...
)

plot_tx_context(exon_table, ...)

Arguments

self

An IsoformicExperiment or an exon table.

gene_name

Character vector of gene names or IDs.

assay

Name of the assay used to label transcripts with their mean expression; NULL disables the labels.

highlight_de

Logical, outline isoforms flagged as significant in the stored transcript-level results.

color_palette

Named colour vector per transcript type; defaults to the object's palette or tx_type_palette().

expression

Optional named numeric vector (by transcript ID) used to label transcripts (data frame method).

highlight

Optional character vector of transcript IDs or names to outline (data frame method).

highlight_poison_exons

Logical, outline exons found only in unproductive isoforms of the gene (see poison_exons()).

upstream_offset, downstream_offset

Extra genomic span (bp) shown before and after the gene.

exon_height

Height of exon boxes (0-1).

ncol

Number of facet columns when several genes are plotted.

...

Passed on to methods.

exon_table

Legacy argument of plot_tx_context().

Value

A ggplot object.

Examples

iso <- example_isoformic()
plot_genomic_context(iso, gene_name = "RBPJ")
plot_genomic_context(iso, gene_name = "EGFR", assay = NULL, highlight_de = FALSE)

# Table-based
plot_genomic_context(exon_table(iso, "PNCK"))

Plot Log2 Fold-Changes of a Gene and Its Isoforms

Description

Bar plot of the log2 fold-change of one or more genes next to the fold-changes of each of their transcripts, coloured by transcript type and faded when not significant. With several genes, one panel per gene is drawn. The IsoformicExperiment method uses the stored differential expression results (see de_table()); the data frame method accepts the long table produced by de_table() or join_DEG_DET().

Usage

plot_log2fc(
  self,
  feature,
  feature_column = "gene_name",
  color_palette = NULL,
  ncol = NULL,
  ...
)

plot_log2FC(
  de_data,
  feature,
  feature_column = "gene_name",
  color_palette = NULL,
  ncol = NULL
)

Arguments

self

An IsoformicExperiment or a long DE table.

feature

Character vector of gene names (or IDs, or transcript names, matched against feature_column).

feature_column

Column of the DE table used to select features (default "gene_name").

color_palette

Named colour vector per transcript type; defaults to the object's palette or tx_type_palette().

ncol

Number of facet columns, NULL for automatic.

...

Passed on to methods.

de_data

A long DE table (see de_table()).

Value

A ggplot object.

Examples

iso <- example_isoformic()
plot_log2fc(iso, feature = "RBPJ")
plot_log2fc(iso, feature = c("RBPJ", "EGFR", "PNCK"), ncol = 1)

# Table-based
plot_log2fc(de_table(iso), feature = "RBPJ")

Poly(A) Sites and Alternative Polyadenylation of Transcripts

Description

polya_sites() describes the 3' end of every assayed transcript:

  • tes_pos, tes_group (alternative 3' ends of the gene, from transcript_features()), tes_rank (1 = most proximal 3' end along the direction of transcription), n_tes_groups, is_proximal, is_distal.

  • apa_type relative to the canonical isoform: "same_end", "tandem_utr" (different 3' end, same stop codon: 3' UTR shortening or lengthening), "alternative_last_exon" (different last exon), "intronic" (3' end inside an intron of the canonical isoform, typically a composite terminal exon) or "other".

  • utr3_length (from transcript_orfs() when sequences are available, else from the annotated CDS).

  • polya_signal and polya_signal_distance: the poly(A) signal hexamer (AATAAA, ATTAAA or one of the weaker variants) found in the last signal_window nt of the transcript sequence, and its distance to the 3' end (canonical signals sit 10-30 nt upstream); NA without sequences.

  • With polya_atlas, the nearest atlas site within window bp of the 3' end: pas_site_id, pas_class, pas_tpm, pas_distance, pas_supported. The atlas is the frozen PolyASite 2.0 table (polya_atlas = "polyasite", see frozen_data), a data frame with seqid, cleavage_pos, strand (and optionally site_id, site_class, tpm), or a GENCODE polyAs.gff3.gz file (download_reference(file_type = "polya")).

apa_usage() quantifies per gene, for genes with at least two 3' end groups: the share of expression ending at the distal-most 3' end (distal_fraction) and the abundance-weighted 3' UTR length (weighted_utr3_length), per sample or per group with the change between the last and the first group level. test_apa() tests the change in distal usage between two groups with the quasi-binomial test used by test_productive_fraction(), on counts.

run_apa_enrichment() runs a gene set enrichment analysis (fgsea::fgseaMultilevel()) on the genes ranked by their change in distal usage (rank_by = "delta", the delta_distal_fraction of apa_usage()) or in weighted 3' UTR length (rank_by = "utr3_length", delta_weighted_utr3_length): a positive score is a gene set whose genes move to distal 3' ends, or to longer 3' UTRs, in the last group level. It also takes the table of apa_usage() for two or more groups, so that one table serves several calls.

Usage

polya_sites(
  self,
  gene_name = NULL,
  polya_atlas = NULL,
  window = 50L,
  signal_window = 50L,
  ...
)

read_polya_gff(path)

apa_usage(
  self,
  group = NULL,
  levels = NULL,
  assay = "abundance",
  min_expr = 0,
  as_matrix = FALSE,
  gene_name = NULL,
  ...
)

test_apa(
  self,
  group,
  levels = NULL,
  assay = "counts",
  min_expr = 0,
  gene_name = NULL,
  ...
)

run_apa_enrichment(
  self,
  genesets_list,
  group = NULL,
  levels = NULL,
  assay = "abundance",
  min_size = 15,
  max_size = 500,
  rank_by = c("delta", "utr3_length"),
  min_expr = 0,
  ...
)

Arguments

self

An IsoformicExperiment; for run_apa_enrichment() also the table of apa_usage() for two or more groups.

gene_name

Optional genes (names or IDs) to restrict the result to.

polya_atlas

NULL (no atlas), "polyasite", a data frame or a file path (Parquet table or GENCODE poly(A) GFF3).

window

Distance in bp within which an atlas site supports a 3' end (default 50).

signal_window

Length of the 3' terminal sequence searched for a poly(A) signal (default 50 nt).

...

Passed on to methods; run_apa_enrichment() passes them to fgsea::fgseaMultilevel().

path

Path to a GENCODE polyAs.gff3.gz file.

group

Name of a col_data column defining groups; NULL for per-sample values. The tests and run_apa_enrichment() on an object need it; with a table it is not used.

levels

Levels of group to use, in this order; the change is last - first. Samples of other groups are ignored, as if the object had been subset to these samples, so every returned value comes from the samples kept. NULL takes all the levels of group. The tests (test_productive_fraction(), test_apa()) need exactly two levels.

assay

Transcript assay to use ("abundance" for usage, "counts" for the test).

min_expr

Minimum assay value for an isoform to count (default 0).

as_matrix

Logical, return the genes x samples matrix of distal fractions instead of the summary table.

genesets_list

Named list of character vectors (gene symbols), as returned by read_gmt(), or a named list of such lists: each collection is then tested on its own and the result has a collection column (see run_enrichment()).

min_size, max_size

Minimum and maximum gene set size passed to fgsea.

rank_by

Statistic that ranks the genes in run_apa_enrichment(): "delta" (default), the change in distal fraction, or "utr3_length", the change in weighted 3' UTR length.

Value

Tibbles with one row per transcript (polya_sites()) or per gene (apa_usage(), test_apa()); a matrix for as_matrix = TRUE. run_apa_enrichment() returns the fgsea table with the columns experiment ("distal_fraction" or "weighted_utr3_length"), rank_by and, for several collections, collection.

Examples

iso <- example_isoformic()
pa <- polya_sites(iso, gene_name = "RBPJ")
pa[, c("transcript_name", "tes_rank", "apa_type", "utr3_length", "polya_signal")]
head(apa_usage(iso, group = "condition"))
head(test_apa(iso, group = "condition"))

if (requireNamespace("fgsea", quietly = TRUE)) {
  gmt <- system.file("extdata", "reactome_subset.gmt", package = "isoformic")
  head(run_apa_enrichment(iso, read_gmt(gmt), group = "condition", min_size = 2))
}

Read a Prepared Annotation into Memory

Description

Reads the Parquet tables of an annotation directory (or converts a GFF3/GTF file first, see prepare_isoformic_annotation()) and returns them as a list of tibbles. This is the table-based counterpart of the ⁠annot_data_*()⁠ accessors of IsoformicExperiment.

Usage

prepare_annotation(
  file_path,
  file_type = c("auto", "gff", "gtf"),
  output_path = NULL
)

Arguments

file_path

Path to an annotation directory or to a GFF3/GTF file.

file_type

Passed to prepare_isoformic_annotation() when file_path is a file.

output_path

Passed to prepare_isoformic_annotation().

Value

A named list with tibbles genes, transcripts, exons, seq_regions and a named list metadata.

Examples

gff <- system.file("extdata", "example.gff3", package = "isoformic")
annot <- prepare_annotation(gff, output_path = tempdir())
names(annot)
head(annot$genes)

Exon Table for Selected Genes From an Annotation

Description

Table-based helper returning one row per exon for the transcripts of the requested genes, joined with transcript and gene attributes. This is the input format of the data-frame method of plot_genomic_context(). With an IsoformicExperiment use exon_table() instead.

Usage

prepare_exon_annotation(
  gene_name,
  file_path,
  file_type = c("auto", "gff", "gtf"),
  output_path = NULL
)

Arguments

gene_name

Character vector of gene names (or gene IDs).

file_path

Path to an annotation directory or a GFF3/GTF file.

file_type

Passed to prepare_isoformic_annotation().

output_path

Passed to prepare_isoformic_annotation().

Value

A tibble with columns gene_id, gene_name, transcript_id, transcript_name, transcript_type, exon_id, exon_number, seqid, start_pos, end_pos, strand.

Examples

gff <- system.file("extdata", "example.gff3", package = "isoformic")
exons <- prepare_exon_annotation("RBPJ", gff, output_path = tempdir())
head(exons)

Convert a GFF3/GTF Annotation to Parquet Files

Description

Parses a GENCODE/Ensembl style GFF3 or GTF annotation file with DuckDB in a single pass and writes one Parquet table per feature level (genes, transcripts, exons) plus metadata and sequence-region tables into an annotation directory. This directory is what IsoformicExperiment objects point to through their annot_path property.

Usage

prepare_isoformic_annotation(
  input_path,
  output_path = NULL,
  file_type = c("auto", "gff", "gtf"),
  annot_name = NULL,
  overwrite = FALSE,
  haplotype = NULL
)

Arguments

input_path

Path to a GFF3 or GTF file, optionally gzip-compressed.

output_path

Directory under which the annotation directory is created. NULL (default) uses get_isoformic_cache().

file_type

"auto" (default) detects the format from the file extension; otherwise "gff" or "gtf".

annot_name

Name of the annotation directory. Defaults to the input file name, lower-cased, with dots replaced by underscores.

overwrite

Logical. Re-create the annotation directory even if a complete one already exists.

haplotype

Optional label (for example "maternal" or "hap1") stored in the haplotype column of every table, for annotations of one haplotype of a phased assembly. See merge_annotations().

Details

Reading a full human GENCODE release (3 to 4 million features, gzip-compressed) takes under a minute; the result is cached so repeated calls with the same file and output location return immediately.

The parser is vocabulary-agnostic so that annotations from different providers and assemblies work the same way:

  • GENCODE GFF3/GTF (GRCh38, GRCm39): gene/transcript/exon features with gene_id, transcript_id, gene_type, transcript_type.

  • Ensembl and Ensembl Rapid Release GFF3 (e.g. T2T-CHM13 GCA_009914755.4): ncRNA_gene, mRNA, lnc_RNA, ... features, ⁠gene:⁠/⁠transcript:⁠ prefixed IDs, biotype, rank.

  • NCBI RefSeq GFF3 (e.g. GCF_009914755.1_T2T-CHM13v2.0): ⁠gene-⁠/⁠rna-⁠ prefixed IDs, gene_biotype, mRNA/lnc_RNA/miRNA features and pseudogenes carrying exons directly.

  • T2T consortium Liftoff and CAT/Liftoff GFF3 (RefSeq or GENCODE lifted to CHM13) and HPRC per-haplotype CAT annotations: transcript_biotype, gbkey, and the source_gene / source_transcript attributes, kept as source_gene_id / source_transcript_id so that lifted annotations can be mapped back to the GRCh38 GENCODE or RefSeq identifiers.

  • MANE GFF3/GTF and CHESS GFF3 (same vocabulary as GENCODE/RefSeq).

  • FANTOM CAT (FANTOM5 lv1-lv4) and FANTOM6 CAT GTF: ⁠__na⁠ placeholders become NA, geneClass is used as the gene (and, when the transcript has no type, the transcript) type, and geneCategory, DHS_type, coding_status, cumulative_support and TIEScore are kept. CAGE cluster identifiers come from the FANTOM ID mapping table, see add_fantom_cat_tables().

  • StringTie, Bambu, FLAIR, IsoQuant and SQANTI3 GTF files from long-read or assembled transcriptomes: reference_id/cmp_ref, ref_gene_id and ref_gene_name populate the source identifiers and gene names; novel transcripts without a biotype get transcript_type = NA until add_sqanti_classification() assigns SQANTI3 structural categories.

Genes are features of a gene-like type or parents of transcripts; transcripts are features of a transcript-like type or parents of exons. Transcript types are normalised (mRNA to protein_coding, lnc_RNA to lncRNA) and fall back to the feature type (miRNA, snRNA, ...) when no biotype attribute exists.

  • genes: gene_id, gene_name, gene_type, source_gene_id, gene_class, gene_category, dhs_type, coding_status, cumulative_support (FANTOM CAT attributes, NA elsewhere), haplotype, seqid, start_pos, end_pos, strand.

  • transcripts: transcript_id, transcript_name, transcript_type, gene_id, source_gene_id, source_transcript_id, tags (comma-separated tag attributes such as MANE_Select, basic, Ensembl_canonical), is_canonical (TRUE for MANE Select, Ensembl canonical or RefSeq Select transcripts), coding_status (FANTOM CAT), transcript_support_level (GENCODE TSL), tie_score (FANTOM CAT TIEScore), cds_start, cds_end, cds_length (aggregated from the CDS features; NA for non-coding transcripts), haplotype, seqid, start_pos, end_pos, strand, n_exons, tx_length.

  • exons: exon_id, transcript_id, exon_number, haplotype, seqid, start_pos, end_pos, strand.

  • metadata: key, value (source file, format, header pragmas, creation time).

  • seq_regions: seqid, start_pos, end_pos.

Value

The path to the annotation directory (character string).

Examples

gff <- system.file("extdata", "example.gff3", package = "isoformic")
annot_dir <- prepare_isoformic_annotation(gff, output_path = tempdir())
list.files(annot_dir)
head(read_parquet(file.path(annot_dir, "annot_data_transcripts.parquet")))

Prepare Expression Profile Data From Loose Tables

Description

Table-based counterpart of profile_data(): combines a transcript expression table, sample metadata, a transcript-to-gene table and differential expression results into the long profile table consumed by plot_tx_expr(). Gene expression is the sum of the isoform values unless txi_gene is supplied.

Usage

prepare_profile_data(
  txi_transcript,
  sample_metadata,
  tx_to_gene,
  de_result_gene = NULL,
  de_result_transcript = NULL,
  var,
  var_levels = NULL,
  txi_gene = NULL,
  gene_name = NULL,
  pvalue_cutoff = 0.05,
  lfc_cutoff = 1,
  use_fdr = TRUE
)

Arguments

txi_transcript

Transcript expression: a matrix or data frame with transcript IDs as row names or in a transcript_id column, or a tximport list (its abundance element is used).

sample_metadata

Data frame whose first column (or sample_id column) holds the sample IDs and that contains the var column.

tx_to_gene

Data frame with transcript_id, gene_id, transcript_name, gene_name and transcript_type columns (see make_tx_to_gene()).

de_result_gene

Gene-level results with gene_id or gene_name, log2FC and qvalue/pvalue columns. May be NULL.

de_result_transcript

Transcript-level results with transcript_id or transcript_name, log2FC and qvalue/pvalue columns. May be NULL.

var

Name of the grouping column in sample_metadata.

var_levels

Levels of var to show, in this order; samples of other groups are ignored. NULL uses the factor levels or the order of appearance.

txi_gene

Optional gene expression table (same formats as txi_transcript, with gene IDs).

gene_name

Optional genes to keep (names or IDs); NULL keeps all.

pvalue_cutoff, lfc_cutoff, use_fdr

Significance cutoffs.

Value

A tibble in the format described in profile_data().

Examples

iso <- example_isoformic()
prof <- prepare_profile_data(
  txi_transcript = assay(iso, "abundance"),
  sample_metadata = col_data(iso),
  tx_to_gene = tx_annot(iso),
  de_result_gene = de_gene(iso),
  de_result_transcript = de_tx(iso),
  var = "condition",
  gene_name = "RBPJ"
)
head(prof)

Productivity of Transcripts and Genes

Description

The biotype split used by the workflow (protein coding versus retained intron, nonsense-mediated decay, ...) is a proxy. These functions make productivity a computed, graded property of every transcript and summarise it per gene:

  • transcript_productivity() classifies each assayed transcript as "productive" (complete ORF, no predicted NMD, same ORF as the canonical isoform), "altered_productive" (complete ORF, no NMD, but a different ORF than the canonical isoform: alternative start, in-frame change, frameshift or stop in novel sequence), "unproductive" (no ORF, premature stop codon by the 50-nt rule, no stop codon, an unproductive biotype such as nonsense_mediated_decay, retained_intron, protein_coding_CDS_not_defined, protein_coding_LoF, or a longest ORF without coding potential), "noncoding" (transcripts of genes without any coding isoform) or "uncertain" (incomplete CDS annotation without a premature stop, a credible ORF unrelated to the canonical one, FANTOM uncertain_coding). The reason column explains each call and source tells whether it came from the sequence ("sequence", when the annotation has transcript sequences, see extract_transcript_sequences() and transcript_orfs()), the annotation ("annotation") or external evidence ("evidence"). Evidence columns take precedence, in this order: a productivity_evidence column added with add_annotation_columns(), a validated NMD exon (add_nmd_exons()), a Ribo-seq ORF matching the transcript's ORF (add_riboseq_orfs()), an APPRIS principal isoform (add_appris()).

  • productive_fraction() is the share of a gene's expression carried by productive (and altered productive) isoforms, per sample or per group, with the difference between the last and the first group level. A gene whose expression is flat while its productive fraction drops is a post-transcriptional regulation call that gene-level differential expression misses. With inferential replicates (inf_reps, Salmon bootstraps or Gibbs samples) it reports the uncertainty of each fraction, and with a reference (gtex_reference()) the difference to the healthy-tissue baseline.

  • productivity_fractions() splits the gene's expression over all productivity classes and, for unproductive isoforms, over the mechanism (nmd, retained_intron, no_orf, non_stop, other).

  • test_productive_fraction() tests the change in productive fraction between two groups on counts, with a quasi-binomial model per gene (pooled proportions per group, Pearson over-dispersion, t test on the log odds ratio, BH adjustment).

  • run_productivity_enrichment() ranks genes by the change in productive fraction between two groups and runs gene set enrichment (fgsea) on gene symbols, which captures regulated unproductive splicing (AS-NMD) directly.

  • poison_exons() lists exons that occur only in unproductive isoforms of genes that also have productive isoforms and that do not overlap any exon of a productive isoform (cassette poison / NMD exons, as opposed to retained introns or alternative splice sites); plot_genomic_context() outlines them with highlight_poison_exons.

  • benchmark_productivity() measures the rules against the annotation biotypes: recall of nonsense_mediated_decay and retained_intron transcripts by the sequence/structure rules alone, and the share of protein_coding and canonical transcripts called productive.

  • productivity_palette() gives colours for the classes.

Usage

productivity_palette()

transcript_productivity(
  self,
  gene_name = NULL,
  nmd_rule = 50,
  use_biotype = TRUE,
  use_sequence = TRUE,
  use_evidence = TRUE,
  coding_cutoff = 0.364,
  ...
)

productive_fraction(
  self,
  group = NULL,
  levels = NULL,
  assay = "abundance",
  include_altered = TRUE,
  as_matrix = FALSE,
  gene_name = NULL,
  min_expr = 0,
  inf_reps = NULL,
  reference = NULL,
  ...
)

productivity_fractions(
  self,
  group = NULL,
  levels = NULL,
  assay = "abundance",
  min_expr = 0,
  gene_name = NULL,
  ...
)

test_productive_fraction(
  self,
  group,
  levels = NULL,
  assay = "counts",
  include_altered = TRUE,
  min_expr = 0,
  gene_name = NULL,
  ...
)

run_productivity_enrichment(
  self,
  genesets_list,
  group = NULL,
  levels = NULL,
  assay = "abundance",
  min_size = 15,
  max_size = 500,
  rank_by = c("delta", "delta_z"),
  include_altered = TRUE,
  min_expr = 0,
  inf_reps = NULL,
  ...
)

poison_exons(self, gene_name = NULL, ...)

benchmark_productivity(self, nmd_rule = 50, use_sequence = TRUE, ...)

Arguments

self

An IsoformicExperiment. run_productivity_enrichment() also takes the table of productive_fraction() for two or more groups, so that one table serves several gene set collections; the arguments that build the table (group, levels, assay, include_altered, min_expr, inf_reps) are then ignored.

gene_name

Optional genes (names or IDs) to restrict the result to.

nmd_rule

Distance (nt) from the stop codon to the last junction above which NMD is predicted; default 50.

use_biotype

Logical, also use unproductive biotypes and FANTOM coding status (default TRUE).

use_sequence

Logical, use the sequence-derived ORFs of transcript_orfs() when the annotation has sequences (default TRUE).

use_evidence

Logical, apply the evidence columns (default TRUE).

coding_cutoff

Coding probability below which a longest ORF (one that could not be projected from the canonical start) is not believed (default 0.364).

...

Passed on to methods or to fgsea::fgseaMultilevel().

group

Name of a col_data column defining groups; NULL for per-sample values. run_productivity_enrichment() requires it for an IsoformicExperiment and ignores it for a productive_fraction() table.

levels

Levels of group to use, in this order; the change is last - first. Samples of other groups are ignored, as if the object had been subset to these samples, so every returned value comes from the samples kept. NULL takes all the levels of group. The tests (test_productive_fraction(), test_apa()) need exactly two levels.

assay

Transcript assay to use (default "abundance"; "counts" for the test).

include_altered

Logical, count altered_productive isoforms as productive in productive_fraction() (default TRUE).

as_matrix

Logical, return the genes x samples matrix of productive fractions instead of the summary table.

min_expr

Minimum assay value for an isoform to contribute (default 0): isoforms below it count as zero.

inf_reps

Optional list of transcript matrices (inferential replicates with the same dimnames as the assay); NULL uses metadata(x)$inf_reps when present and FALSE skips the replicates, which leaves out the standard deviations and delta_z and is much faster. run_productivity_enrichment() reads the replicates only for rank_by = "delta_z".

reference

Optional tibble from gtex_reference(), or a GTEx tissue name, giving the healthy-tissue productive fraction per gene.

genesets_list

Named list of gene symbol vectors (see read_gmt()), or a named list of such lists: each collection is then tested on its own and the result has a collection column (see run_enrichment()).

min_size, max_size

Gene set size limits passed to fgsea.

rank_by

Statistic that ranks the genes in run_productivity_enrichment(): "delta" (default), the change in productive fraction, or "delta_z", that change divided by its standard deviation over the inferential replicates, which moves the genes with an uncertain change towards the middle of the ranking. "delta_z" needs inferential replicates; a change that is the same in every replicate gets the largest delta_z of the table. It reflects the quantification uncertainty only, not the variation between samples.

Value

Tibbles, a matrix for productive_fraction(as_matrix = TRUE), a named character vector for productivity_palette(), a list with summary and confusion tibbles for benchmark_productivity().

Examples

iso <- example_isoformic()
prod <- transcript_productivity(iso, gene_name = "RBPJ")
prod[, c("transcript_name", "transcript_type", "productivity", "reason", "source")]
head(productive_fraction(iso, group = "condition"))
head(productivity_fractions(iso, group = "condition"))
head(test_productive_fraction(iso, group = "condition"))
poison_exons(iso, gene_name = "RBPJ")
benchmark_productivity(iso)$summary

Attach External Productivity Evidence to an Annotation

Description

These functions add evidence columns to the transcript table of the annotation directory of x from the frozen datasets (frozen_data), so that transcript_productivity() can use observed translation and decay instead of rules alone. Identifiers are matched without version.

  • add_appris() adds appris_annotation (PRINCIPAL:1 ... ALTERNATIVE:2, MINOR), appris_principal, appris_score and the method scores (firestar_residues, matador_structure, corsair_conservation, spade_domain_score, thump_tm_helices, trifid_score). Principal isoforms are productive evidence.

  • add_riboseq_orfs() adds riboseq_n_orfs (Ribo-seq ORFs compatible with the transcript's exon structure), riboseq_orf_types, riboseq_main_orf (TRUE when a translated ORF coincides with the transcript's own ORF, from transcript_orfs() when sequences are available or else from the annotated CDS) and riboseq_uorf. A translated main ORF is productive evidence. Phase 1 ORFs list their compatible transcripts; all ORFs are also matched by exon-block compatibility (every block inside an exon, consecutive blocks in consecutive exons, internal block boundaries on exon boundaries).

  • add_nmd_exons() adds nmd_validated_exon, TRUE when the transcript contains an exon with the exact coordinates of an NMD-inducing cassette exon validated by NMD inhibition (Karousis et al. 2021), or is one of the listed NMD isoforms. This is unproductive evidence.

Each function returns the annotation directory path invisibly and invalidates the object caches of x (the next call to a method rereads the annotation).

Usage

add_appris(x, table = NULL)

add_riboseq_orfs(x, table = NULL)

add_nmd_exons(x, table = NULL)

Arguments

x

An annotation directory path or an IsoformicExperiment.

table

A data frame with the dataset, or a path to its Parquet file; NULL (default) fetches the frozen dataset with fetch_frozen_data().

Value

The annotation directory path, invisibly.

Examples

## Not run: 
iso <- example_isoformic()
add_appris(iso)
add_riboseq_orfs(iso)
add_nmd_exons(iso)
prod <- transcript_productivity(iso, gene_name = "RBPJ")
prod[, c("transcript_name", "productivity", "reason", "source")]

## End(Not run)

Expression Profiles of Genes and Their Isoforms Across Groups

Description

profile_data() summarises the expression of selected genes and of each of their isoforms per sample group (mean and standard deviation), and attaches the differential expression calls. plot_tx_expr() draws the result: one panel per gene, one line per feature (the gene plus its isoforms), coloured by transcript type and faded when not differentially expressed. The table-based prepare_profile_data() produces the same table from loose tables.

Usage

profile_data(self, gene_name, group, levels = NULL, assay = "abundance", ...)

plot_tx_expr(
  self,
  gene_name = NULL,
  group = NULL,
  levels = NULL,
  assay = "abundance",
  log_scale = TRUE,
  label = TRUE,
  ncol = NULL,
  color_palette = NULL,
  ...
)

Arguments

self

An IsoformicExperiment, or (for plot_tx_expr()) a profile table produced by profile_data()/prepare_profile_data().

gene_name

Character vector of gene names or IDs to profile.

group

Name of the col_data column defining the groups (x axis).

levels

Levels of group to show, in this order. Samples of other groups are ignored, as if the object had been subset to these samples. NULL takes all the levels of group (factor levels, else order of appearance). For a profile table, the groups of the table to draw.

assay

Name of the transcript assay to summarise (default "abundance").

...

Passed on to methods.

log_scale

Logical, show log2(mean + 1) on the y axis.

label

Logical, label features at the last group level.

ncol

Number of facet columns, NULL for automatic.

color_palette

Named colour vector per transcript type; defaults to the object's palette or tx_type_palette().

Value

profile_data() returns a tibble with columns feature_id, feature_name, feature_type, gene_id, gene_name, group, mean_expr, sd_expr, n_samples and is_de; the grouping variable name is stored in the "group_var" attribute. plot_tx_expr() returns a ggplot object.

Examples

iso <- example_isoformic()
head(profile_data(iso, gene_name = "RBPJ", group = "condition"))
plot_tx_expr(iso, gene_name = c("RBPJ", "EGFR"), group = "condition")

Read Oarfish Quantifications Into an IsoformicExperiment

Description

Oarfish quantifies long reads (Oxford Nanopore and PacBio) against a transcriptome. For every sample it writes, next to a common output prefix, ⁠<prefix>.quant⁠ (transcript name, length and estimated read count), ⁠<prefix>.ambig_info.tsv⁠ (reads that map to the transcript alone and reads shared with others), ⁠<prefix>.meta_info.json⁠ and, with --num-bootstraps, ⁠<prefix>.infreps.pq⁠ (the bootstrap replicates as a Parquet table). read_oarfish() reads them like read_salmon() reads Salmon output: an IsoformicExperiment with counts, length and abundance assays, and, with inferential = TRUE, the uncertainty tables of add_uncertainty().

Usage

read_oarfish(
  paths,
  annot_path,
  col_data = NULL,
  experiment_name = NULL,
  ignore_after_bar = TRUE,
  drop_unannotated = FALSE,
  inferential = FALSE
)

Arguments

paths

Output prefixes of Oarfish (the value of -o), paths to the .quant files, or directories holding a single .quant file. Names, when present, are the sample IDs; otherwise the prefix is used.

annot_path

Annotation directory or GFF3/GTF file (see prepare_isoformic_annotation()).

col_data

Optional data frame of sample metadata whose first column (or a sample_id column) matches the sample IDs. When NULL, a minimal table with just sample_id is created.

experiment_name

Optional experiment name.

ignore_after_bar

Logical. Keep only the part of transcript names before the first | (GENCODE FASTA headers used as Salmon references).

drop_unannotated

Logical. Drop transcripts absent from the annotation (with a message) instead of failing.

inferential

Logical. Read the bootstrap replicates and the ambiguity counts and compute the uncertainty tables with add_uncertainty(). The samples must have been quantified with --num-bootstraps.

Details

Oarfish does not write TPM; the abundance assay is computed from the read counts and the transcript lengths (reads per base, scaled to one million). The ambiguity counts of .ambig_info.tsv play the role of the equivalence classes of Salmon in equivalence_support(): unique_fraction is the share of reads mapped to the transcript alone, while n_classes is not available. The functions read_inferential_replicates(), equivalence_support(), salmon_run_qc() and add_uncertainty() accept Oarfish prefixes as paths, but not together with Salmon directories.

Value

An IsoformicExperiment.

Examples

prefixes <- file.path(
  system.file("extdata", "oarfish", package = "isoformic"),
  c("control_1", "control_2", "treated_1")
)
names(prefixes) <- basename(prefixes)
annot <- system.file(
  "extdata", "example_experiment", "annotation",
  package = "isoformic"
)
iso <- read_oarfish(prefixes, annot_path = annot, inferential = TRUE)
iso
head(tx_uncertainty(iso))

Read Oarfish single-cell quantifications

Description

With --single-cell, Oarfish quantifies a transcriptome-aligned BAM whose reads carry a cell barcode (CB:Z tag) and writes, next to its output prefix, ⁠<prefix>.count.mtx⁠ (a Matrix Market table of cells by transcripts), ⁠<prefix>.barcodes.txt⁠, ⁠<prefix>.features.txt⁠ and ⁠<prefix>.meta_info.json⁠. It draws no replicates in this mode.

Usage

read_oarfish_sc_counts(path, ignore_after_bar = TRUE)

read_oarfish_sc(
  path,
  cells,
  annot_path,
  col_data = NULL,
  experiment_name = NULL,
  min_cells = 1L,
  ignore_after_bar = TRUE,
  drop_unannotated = FALSE
)

Arguments

path

The output prefix of Oarfish (the value of -o), the .count.mtx file, or a directory holding a single .count.mtx file.

ignore_after_bar

Logical. Keep only the part of transcript names before the first | (GENCODE FASTA headers used as Salmon references).

cells

A data frame with a barcode column and a sample_id column.

annot_path

Annotation directory or GFF3/GTF file (see prepare_isoformic_annotation()).

col_data

Optional sample metadata with a sample_id column; the number of cells and reads of each sample are added as n_cells and n_reads.

experiment_name

Optional experiment name.

min_cells

Samples with fewer cells are dropped.

drop_unannotated

Logical. Drop transcripts absent from the annotation (with a message) instead of failing.

Details

  • read_oarfish_sc_counts() returns the non-zero counts as a long table, one row per cell and transcript.

  • read_oarfish_sc() sums the cells of each sample (a pseudobulk) and returns an IsoformicExperiment with counts, length (from the annotation) and abundance (TPM computed from both) assays, so the isoform analyses of the package apply to single-cell data at the level of samples or cell types. cells says which sample each barcode belongs to; barcodes absent from it are dropped. To compare cell types, give each combination of sample and cell type its own sample_id and describe it in col_data.

Value

read_oarfish_sc_counts(): a tibble with barcode, transcript_id and count. read_oarfish_sc(): an IsoformicExperiment.

Examples

dir <- system.file("extdata", "oarfish_sc", package = "isoformic")
counts <- read_oarfish_sc_counts(file.path(dir, "out"))
head(counts)
cells <- read.delim(file.path(dir, "cells.tsv"))
iso <- read_oarfish_sc(
  file.path(dir, "out"),
  cells = cells,
  annot_path = system.file(
    "extdata", "example_experiment", "annotation",
    package = "isoformic"
  )
)
col_data(iso)

Read Salmon Quantifications Into an IsoformicExperiment

Description

Reads quant.sf files produced by Salmon (⁠salmon quant⁠) directly with DuckDB, without going through tximport, and returns an IsoformicExperiment with transcript-level abundance (TPM), counts (NumReads) and length (EffectiveLength) assays. Gene-level assays are derived lazily by the object (see gene_assays()).

Usage

read_salmon(
  paths,
  annot_path,
  col_data = NULL,
  experiment_name = NULL,
  ignore_after_bar = TRUE,
  drop_unannotated = FALSE,
  inferential = FALSE
)

Arguments

paths

Character vector of Salmon output directories (containing quant.sf) or paths to quant.sf files. Names, when present, are used as sample IDs; otherwise the directory name is used.

annot_path

Annotation directory or GFF3/GTF file (see prepare_isoformic_annotation()).

col_data

Optional data frame of sample metadata whose first column (or a sample_id column) matches the sample IDs. When NULL, a minimal table with just sample_id is created.

experiment_name

Optional experiment name.

ignore_after_bar

Logical. Keep only the part of transcript names before the first | (GENCODE FASTA headers used as Salmon references).

drop_unannotated

Logical. Drop transcripts absent from the annotation (with a message) instead of failing.

inferential

Logical. Read the inferential replicates, equivalence classes and run metadata of the Salmon directories and compute the uncertainty tables with add_uncertainty() (default settings; call that function for other cutoffs or a contrast). The directories must have been quantified with --numGibbsSamples or --numBootstraps.

Details

All files are read in one DuckDB query and pivoted to wide matrices, so reading tens of samples with 200,000 transcripts each takes seconds. Inferential replicates (Gibbs/bootstrap samples) are read only with inferential = TRUE, which also computes the uncertainty tables of add_uncertainty(); for swish they are imported with tximeta/fishpond and converted with as_isoformic().

Value

An IsoformicExperiment.

Examples

quant_dirs <- list.files(
  system.file("extdata", "mini_quants", package = "isoformic"),
  full.names = TRUE
)
names(quant_dirs) <- sub("_quant$", "", basename(quant_dirs))
annot <- system.file("extdata", "mini_annotation", package = "isoformic")
iso <- read_salmon(quant_dirs, annot_path = annot)
iso

Read the transcript groups that Terminus builds

Description

Terminus groups the transcripts whose abundances the reads cannot estimate separately and reports one consensus grouping for a set of samples. Run it on Salmon output made with --numGibbsSamples (or --numBootstraps), --dumpEq and --dumpEqWeights:

Usage

read_terminus_groups(path, ignore_after_bar = TRUE)

Arguments

path

The clusters.txt file, or a folder that holds it (the output folder of one sample, or the folder given to -o when it holds one sample folder).

ignore_after_bar

Logical. Keep only the part of transcript names before the first |.

Details

terminus group -d quant/sample1 -o terminus/out
terminus collapse -d quant/sample1 quant/sample2 -o terminus/out

collapse writes clusters.txt in the output folder of every sample: one line per group, the name of the group followed by its transcripts, separated by commas. read_terminus_groups() reads that file into a long table that add_uncertainty() accepts in its groups argument, so that the groups of Terminus replace the groups built from the correlation of the replicates.

Value

A tibble with group_id, transcript_id and group_size.

See Also

add_uncertainty(), isoform_ambiguity()

Examples

clusters <- tempfile(fileext = ".txt")
writeLines(
  c(
    "NewTr1,ENST00000831217.1,ENST00000831165.1",
    "NewTr2,ENST00000831423.1,ENST00000831157.1,ENST00000831246.1"
  ),
  clusters
)
read_terminus_groups(clusters)

Run Terminus on Salmon output from R

Description

run_terminus() builds the consensus groups of Terminus for a set of samples without leaving R: it runs ⁠terminus group⁠ on every Salmon output directory, then ⁠terminus collapse⁠ on all of them, and returns the groups read by read_terminus_groups(), ready for add_uncertainty(groups = ). Terminus is installed from Bioconda into a conda environment managed by condathis the first time it is needed.

Usage

run_terminus(
  paths,
  output_dir,
  consensus_thresh = 0.5,
  min_spread = 0.1,
  threads = 4L,
  workers = 1L,
  keep_logs = FALSE,
  env_name = "terminus-env",
  verbose = "output"
)

Arguments

paths

Salmon output directories (or paths to their quant.sf).

output_dir

Folder for the Terminus output; one subfolder per sample holds groups.txt and, after the consensus, clusters.txt and the collapsed quantification.

consensus_thresh

Share of samples in which two transcripts must be grouped for the consensus to group them (--consensus-thresh).

min_spread

Minimum spread of a transcript for its edges to be collapse candidates (--min-spread).

threads

Threads for writing the collapsed quantifications.

workers

Number of samples grouped at the same time (in parallel processes on Unix-like systems). Each one needs several gigabytes of memory for a human transcriptome.

keep_logs

Logical, keep the logs of ⁠terminus group⁠.

env_name

Name of the conda environment with Terminus.

verbose

Passed to condathis::run().

Details

Every directory needs inferential replicates (--numGibbsSamples or --numBootstraps) and equivalence classes with their weights (--dumpEq --dumpEqWeights); salmon_quant() writes both. Without the weights Terminus stops with an unhelpful error, so the directories are checked first. Terminus names the folder of each sample after the basename of its Salmon directory, which must therefore be unique.

⁠terminus group⁠ writes a log of several gigabytes per human sample (delta.log) that collapse does not use; it is deleted as soon as each sample is grouped, and the other logs after the consensus, unless keep_logs = TRUE.

Value

The consensus groups, as returned by read_terminus_groups(), with the output folder in the output_dir attribute.

See Also

read_terminus_groups(), add_uncertainty(), salmon_quant()

Examples

## Not run: 
groups <- run_terminus(quant_dirs, output_dir = "terminus")
iso <- add_uncertainty(iso, paths = quant_dirs, groups = groups)
tx_uncertainty(iso)

## End(Not run)

Build Salmon Index

Description

Create a Salmon index from a reference transcriptome FASTA file.

Usage

salmon_index(
  fasta_path,
  index_path = "salmon_index",
  kmer_len = 31,
  num_threads = 2,
  env_name = "salmon-env",
  is_gencode = FALSE,
  decoy_fasta = NULL,
  clip_poly_a = TRUE
)

Arguments

fasta_path

Path to the reference transcriptome FASTA file.

index_path

Directory path to save the Salmon index (default is "salmon_index").

kmer_len

K-mer length for the index (default is 31).

num_threads

Number of threads to use (default is 2).

env_name

Name of the conda environment with Salmon installed (default is "salmon-env").

is_gencode

Logical indicating if the FASTA is from GENCODE (default is FALSE); the transcript names are then truncated at the first | so that they match the annotation.

decoy_fasta

Optional path to a FASTA file containing decoy sequences (default is NULL).

clip_poly_a

Logical indicating whether to clip poly-A tails (default is TRUE).

Details

The index must be built with the same Salmon major version used for salmon_quant(): Salmon 2 (the Rust rewrite) cannot read indices built by Salmon 1.x and rejects them with an error. Rebuild the index after upgrading.

Value

processx style output list.


Run Salmon Quantification

Description

Perform transcript quantification using Salmon's selective-alignment-based mode from raw RNA-seq reads.

Usage

salmon_quant(
  input_r1,
  input_r2 = NULL,
  index_path = "salmon_index",
  output_dir = "quant_output",
  num_threads = 8,
  num_gibbs = 30,
  min_score_fraction = "0.65",
  env_name = "salmon-env"
)

Arguments

input_r1

Path to the FASTQ file for read 1 (or single-end reads).

input_r2

Optional path to the FASTQ file for read 2 (paired-end reads).

index_path

Path to the Salmon index directory (default is "salmon_index").

output_dir

Directory to save the quantification output (default is "quant_output").

num_threads

Number of threads to use (default is 8).

num_gibbs

Number of Gibbs samples (inferential replicates) drawn per sample (default is 30). They quantify how well each transcript abundance is determined by the reads and are used by add_uncertainty() and by swish; 30 is enough for those summaries, and more only costs time and disk space. Set it to 0 to skip them.

min_score_fraction

Minimum score fraction for alignments (default is "0.65").

env_name

Name of the conda environment with Salmon installed (default is "salmon-env").

Details

The command enables the sequence, GC and positional bias corrections, allows dovetailing mates and soft-clipped overhangs, writes the equivalence classes with their weights (--dumpEq --dumpEqWeights) and draws num_gibbs Gibbs samples (⁠aux_info/bootstrap/⁠) so that inferential replicates are available for swish. Selective alignment and the variational Bayes optimiser are Salmon defaults and are not passed explicitly; Salmon 2 quantifies deterministically (identical output for any thread count). Single-end reads are passed with --unmatedReads.

Value

processx style output list.


Splice-Site Strength from the Annotation and the Genome

Description

Scores the donor (5') and acceptor (3') splice site of every intron with position weight matrices built from the annotation itself, and reports the weakest site of every transcript. A weak site is one way for an isoform to be rare or to be a splicing error; the score is evidence to read next to transcript_productivity(), not a classifier.

  • extract_splice_sites(x, genome_fasta) cuts the sequences around the splice sites out of a genome FASTA and stores them in the annotation directory. extract_transcript_sequences() does the same when it is given a genome FASTA, so this is only needed for directories whose sequences came from a transcript FASTA.

  • splice_site_strength(x) returns one row per transcript, or one row per intron with by = "intron".

Usage

extract_splice_sites(x, genome_fasta, overwrite = FALSE, chunk_bytes = 6.4e+07)

has_splice_sites(x)

splice_site_strength(
  self,
  gene_name = NULL,
  by = c("transcript", "intron"),
  ...
)

Arguments

x

An annotation directory path or an IsoformicExperiment.

genome_fasta

Path to a genome FASTA file (.fa, .fa.gz).

overwrite

Logical, replace an existing table (default FALSE).

chunk_bytes

Number of bytes read per chunk while streaming.

self

An annotation directory path or an IsoformicExperiment. An experiment reports its own transcripts.

gene_name

Optional gene names or IDs to keep.

by

"transcript" (default) or "intron".

...

Unused.

Details

The donor window holds the last 3 exonic and the first 6 intronic bases, the acceptor window the last 20 intronic and the first 3 exonic bases, in the direction of transcription (the windows of MaxEntScan, Yeo and Burge 2004). The matrices are trained on the unique introns of the canonical transcripts (is_canonical, see prepare_isoformic_annotation()), or on all introns when the annotation marks fewer than 100 canonical introns. A score is the sum over the window of log2(frequency / background), with the background taken from the base composition of the training windows and half a pseudocount per base. Positive means closer to the consensus.

Limits. The matrices assume that positions are independent, so they are weaker than MaxEntScan or a sequence model, and they describe the major (GT-AG) spliceosome: U12 introns and other non-canonical sites get low scores whatever their real efficiency (n_noncanonical counts the introns that are not GT-AG). Canonical transcripts train the matrices, so their own scores are slightly optimistic. Windows that run off the sequence or hold a base other than A, C, G or T are not scored.

Value

  • extract_splice_sites(): the path of the written Parquet file, invisibly. The table has seqid, strand, intron_start, intron_end (1-based, inclusive), donor_seq and acceptor_seq.

  • splice_site_strength(): a tibble. By transcript: transcript_id, gene_id, gene_name, n_introns, n_scored, weakest_donor, weakest_acceptor, mean_donor, mean_acceptor and n_noncanonical; transcripts without introns have NA scores. By intron: one row per transcript and intron with the coordinates, the two window sequences, donor_score, acceptor_score and canonical_dinucleotides.

References

Yeo, G., Burge, C.B. (2004). Maximum entropy modeling of short sequence motifs with applications to RNA splicing signals. Journal of Computational Biology 11(2-3), 377-394.

See Also

extract_transcript_sequences(), transcript_productivity()

Examples

gff <- system.file("extdata", "example.gff3", package = "isoformic")
annot <- prepare_isoformic_annotation(
  gff,
  output_path = tempdir(),
  annot_name = "splice_demo"
)
has_splice_sites(annot)
## Not run: 
genome <- download_reference(file_type = "genome_fasta", region = "primary")
extract_splice_sites(annot, genome_fasta = genome)
splice_site_strength(annot)

## End(Not run)

Summarize Transcript-Level Matrices to Gene Level

Description

Sums the values of all isoforms of a gene. A length assay is combined as the abundance-weighted mean when an abundance assay is supplied in the same list (the tximport convention). This is the function used by gene_assays() and can be called directly on matrices.

Usage

summarize_to_gene(x, tx_to_gene)

Arguments

x

A numeric matrix (transcripts in rows) or a named list of such matrices sharing row names.

tx_to_gene

Data frame with transcript_id and gene_id columns.

Value

A matrix, or a named list of matrices, with genes in rows.

Examples

iso <- example_isoformic()
g <- summarize_to_gene(assay(iso, "abundance"), tx_to_gene(iso))
head(g)

Test differential transcript usage

Description

test_usage() tests whether the share of a gene's expression carried by each isoform differs between groups of samples, with one of three established frameworks:

  • "diffsplice": edgeR quasi-likelihood fits and diffSplice, the pipeline of the 2025 Nucleic Acids Research paper below. Fast, and the one designed for counts divided by the read-ambiguity overdispersion.

  • "satuRn": quasi-binomial models of transcript usage (Gilis et al., 2021), suited to many samples and to single-cell data.

  • "DEXSeq": negative binomial models of exon (here transcript) usage (Anders et al. 2012), the slowest and often the most conservative.

Recent benchmarks of usage tests (2024 and 2025) rank these among the best; none dominates, so the backend is an argument. With inferential replicates in the object (see add_uncertainty()), the counts are divided by the overdispersion that the read ambiguity adds (see inferential_overdispersion()) before the test (scale = TRUE).

Transcripts are kept when at least min_count reads and a share of min_prop of the gene fall on them in as many samples as the smallest group, and genes need two such transcripts.

The gene-level p-value combines the transcript p-values of a gene with Simes' method, and both levels are adjusted with the Benjamini-Hochberg procedure within each contrast, so that the three backends report the same columns.

With more than two groups, every contrast of contrasts is tested and the results are stacked, one block per contrast. "diffsplice" and "satuRn" fit all the groups once and test each contrast on that fit, so the dispersions use every sample; "DEXSeq" compares a model with and without a group effect, so it is fitted on the samples of the two groups of each contrast.

contrasts = "omnibus" gives one p-value per transcript for a difference among any of the groups, with contrast = "omnibus" and no fold-change (usage_log2FC is NA; look at the contrasts for the direction). "DEXSeq" compares its models with and without the group effect on all the samples. edgeR and satuRn test one contrast at a time, so for them the p-value is the Simes combination of the contrasts of every level against the first: the groups can only differ if some level differs from the first, and those contrasts share the reference, so they are positively correlated and Simes' test keeps its error rate.

Usage

test_usage(
  self,
  group,
  levels = NULL,
  contrasts = NULL,
  method = "diffsplice",
  assay = "counts",
  scale = NULL,
  min_count = 10,
  min_prop = 0.1,
  workers = 1L,
  gene_name = NULL,
  ...
)

Arguments

self

An IsoformicExperiment.

group

Column of col_data() with the groups to compare.

levels

Levels of group to use, reference first. Samples of other groups are ignored. NULL takes all the levels of group.

contrasts

The comparisons to test: NULL (default) compares every level with the first one; "pairwise" tests every pair of levels (the later level against the earlier one); "omnibus" tests whether usage differs among any of the groups (see Details); otherwise a list of c(numerator, denominator) pairs of levels, or one such pair. With two levels the default is the single contrast second against first.

method

"diffsplice", "satuRn" or "DEXSeq". The backend must be installed.

assay

Counts assay to test.

scale

Logical, divide the counts by the overdispersion of the replicates. NULL (default) does it when the object has replicates. In a read-split experiment (technical replicates of the same libraries, see the uncertainty article) this removed most false positives of "diffsplice" and "DEXSeq" and made their calls reproducible, so keep it on.

min_count, min_prop

Filters described above.

workers

Number of workers for satuRn and DEXSeq (parallel on Unix-like systems).

gene_name

Gene names or IDs to keep in the result. The filter is applied after the test.

...

Unused.

Value

A tibble with one row per tested transcript and contrast: gene_id, gene_name, transcript_id, transcript_name, transcript_type, contrast ("numerator vs denominator"), usage_log2FC (the change in usage on the log2 scale: for "diffsplice" the transcript against the other transcripts of the gene, for "satuRn" the log2 odds ratio, for "DEXSeq" the usage fold-change), pvalue, qvalue, gene_pvalue, gene_qvalue, method and scaled.

References

Dividing out quantification uncertainty enables assessment of differential transcript usage with limma and edgeR (2025). Nucleic Acids Research, doi:10.1093/nar/gkaf1305.

Gilis J et al. (2021). satuRn: scalable analysis of differential transcript usage for bulk and single-cell RNA-sequencing applications. F1000Research 10:374.

Anders S, Reyes A, Huber W (2012). Detecting differential usage of exons from RNA-seq data. Genome Research 22:2008-2017.

See Also

test_productive_fraction(), test_apa(), de_confidence()

Examples

iso <- example_isoformic()
if (requireNamespace("edgeR", quietly = TRUE)) {
  res <- test_usage(iso, group = "condition", method = "diffsplice")
  head(res)
  table(res$contrast)
}

Structural and Coding Features of Transcripts

Description

Computes, for every assayed transcript, features that go beyond the biotype label, from the exon and CDS coordinates of the annotation:

  • Ends: tss_pos, tes_pos (genomic positions of the transcription start and end), tss_group and tes_group (integer labels of alternative promoters / 3' ends within the gene; starts or ends closer than end_window bp share a group).

  • ORF: has_cds, cds_complete (FALSE when the annotation flags an incomplete CDS with cds_start_NF/cds_end_NF), orf_length (nt), utr5_length, utr3_length.

  • NMD rule: stop_to_last_junction, the distance in transcript coordinates from the stop codon to the last exon-exon junction, and nmd_predicted (TRUE when that distance exceeds nmd_rule nt, the classical 50-55 nt rule).

  • Comparison with the canonical isoform: canonical_transcript_id (the MANE Select / Ensembl canonical transcript of the gene, else the transcript with the longest CDS, else the longest transcript), orf_fraction_of_canonical and cds_differs_from_canonical.

  • Splicing events relative to the canonical isoform (see splicing_events()): n_skipped_exons, n_novel_exons, n_retained_introns, n_alt_5ss, n_alt_3ss, alt_first_exon, alt_last_exon.

splicing_events() returns the event counts alone; both are cached per object. The data-frame methods accept the exon table of an annotation (see exon_table()) joined with the transcript columns.

Usage

transcript_features(
  self,
  gene_name = NULL,
  nmd_rule = 50,
  end_window = 50,
  ...
)

splicing_events(self, gene_name = NULL, ...)

Arguments

self

An IsoformicExperiment or an annotation directory path.

gene_name

Optional genes (names or IDs) to restrict the result to.

nmd_rule

Distance in nucleotides from the stop codon to the last junction above which NMD is predicted (default 50).

end_window

Distance in bp within which transcription starts (or ends) are grouped as the same promoter (or 3' end); default 50.

...

Passed on to methods.

Value

A tibble with one row per transcript.

Examples

iso <- example_isoformic()
feats <- transcript_features(iso, gene_name = "RBPJ")
feats[, c("transcript_name", "orf_length", "nmd_predicted", "tss_group", "n_skipped_exons")]
splicing_events(iso, gene_name = "EGFR")

Open Reading Frames of Transcripts from Their Sequences

Description

Computes, for every assayed transcript, an open reading frame (ORF) and the sequence-level features that decide whether it is productive. Requires transcript sequences in the annotation directory (see extract_transcript_sequences()). The ORF of each transcript comes from the first applicable source (orf_source):

  1. "annotation": a complete annotated CDS. Its stop codon is added when the annotation excludes it (as GENCODE does) and the ORF is re-read from the annotated start codon to the first in-frame stop, so a CDS that does not match the sequence is corrected (annotation_cds_agrees = FALSE). Transcripts tagged seleno, ribosomal_slippage or non_ATG_start keep the annotated CDS.

  2. "projected": the start codon of the gene's canonical isoform lies in an exon of the transcript and reads ATG there; translation proceeds from that position to the first in-frame stop (the ORFanage approach). This is what rescues novel isoforms without CDS.

  3. "annotation_partial": an annotated CDS flagged incomplete (cds_start_NF / cds_end_NF) whose start could not be projected; the annotated span is kept, and when its 3' end is known the NMD rule still applies (GENCODE annotates many NMD transcripts this way).

  4. "longest": none of the above; the longest ATG-to-stop ORF of at least min_orf_length nt is used and coding_probability tells whether it is believable.

  5. "none": no ORF of at least min_orf_length nt.

From the ORF the function derives the stop codon (NA when translation runs into the transcript end, a non-stop decay substrate), the UTR lengths, uORFs in the 5' UTR (n_uorf, complete upstream ORFs; n_overlapping_uorf, out-of-frame upstream ORFs overlapping the main start), the genomic coordinates of start and stop, whether start and stop are shared with the canonical isoform and whether the reading frame at the stop codon is in frame with the canonical ORF (frame_vs_canonical), and the NMD class:

  • "ptc": the stop lies more than nmd_rule nt upstream of the last exon-exon junction (the 50-nt rule), NMD predicted.

  • "ptc_start_proximal": same, but the ORF is shorter than start_proximal nt; still called unproductive, with the note that such transcripts can escape NMD by translation re-initiation.

  • "non_stop": no in-frame stop codon.

  • "long_3utr": no premature stop, but a 3' UTR longer than long_utr3 nt (default Inf, so the flag is off unless asked for).

  • "none": no NMD feature.

  • NA: no stop codon in a transcript whose 3' end is annotated as incomplete (cds_end_NF / mRNA_end_NF, column end_incomplete), so nothing can be said.

coding_potential() scores every transcript's longest ORF with the Fickett TESTCODE statistic and an in-frame hexamer usage score, combined by a logistic model trained on GENCODE coding versus lncRNA transcripts (see data-raw/build_coding_model.R); coding_probability above coding_cutoff (0.364, the CPAT human cutoff) is called coding.

Usage

transcript_orfs(
  self,
  gene_name = NULL,
  min_orf_length = 90L,
  nmd_rule = 50,
  start_proximal = 150,
  long_utr3 = Inf,
  ...
)

coding_potential(
  self,
  gene_name = NULL,
  min_orf_length = 90L,
  coding_cutoff = 0.364,
  ...
)

Arguments

self

An IsoformicExperiment or an annotation directory path.

gene_name

Optional genes (names or IDs) to restrict the result to.

min_orf_length

Minimum ORF length in nt, stop codon included (default 90, i.e. 29 amino acids).

nmd_rule

Distance (nt) from the stop codon to the last junction above which NMD is predicted; default 50.

start_proximal

ORF length (nt) below which a premature stop is classed ptc_start_proximal instead of ptc; default 150.

long_utr3

3' UTR length (nt) above which long_3utr is flagged; default Inf.

...

Passed on to methods.

coding_cutoff

Coding probability above which a transcript is called coding (default 0.364).

Value

A tibble with one row per transcript.

Stored ORF table

The analysis takes minutes for a whole GENCODE release, so the rows computed are written to annot_data_orfs.parquet in the annotation directory and read back by later calls, sessions and objects that use the same annotation. A stored row is used when the canonical isoform of the gene, among the transcripts of the call, is the one it was computed with, so the result is the same with and without the table. A gene with a transcript that has no such row is computed whole, and its rows are stored when its canonical isoform is the one of the whole annotation. The table is computed again when the transcripts, exons or sequences of the annotation, min_orf_length, the coding potential model (build_coding_model()) or the package version change. It is not written into a read-only directory or the example annotation of the installed package, and options(isoformic.orf_cache = FALSE) turns it off. The warning about sequences that differ in length from their exons is given when the rows are computed, not when they are read back.

See Also

transcript_productivity(), transcript_features()

Examples

iso <- example_isoformic()
orfs <- transcript_orfs(iso, gene_name = "RBPJ")
orfs[, c("transcript_name", "orf_source", "orf_length", "nmd_class", "coding_probability")]

Extract Transcript Sequences into an Annotation Directory

Description

Adds the spliced sequence of every transcript of an annotation directory as annot_data_sequences.parquet, read by transcript_orfs(), coding_potential() and the sequence-aware rules of transcript_productivity(). Sequences come either from a genome FASTA (genome_fasta; exons are cut out of each chromosome, reverse complemented on the minus strand and concatenated in transcript order, so novel transcripts from long-read or assembly annotations are covered) or from a transcript FASTA (transcript_fasta, for example the GENCODE transcripts.fa.gz; sequences are matched by the first token of the header, with and without the identifier version).

The genome is streamed in chunks (plain or gzip-compressed FASTA, no index needed) and only one chromosome is held in memory at a time; a human genome takes a few minutes. Chromosome names are matched to the annotation seqid directly, or after adding or removing a chr prefix. Soft-masked (lower-case) bases are upper-cased. With a genome FASTA the sequences around the splice sites of every intron are written in the same pass (annot_data_splice_sites.parquet, see splice_site_strength()).

Usage

extract_transcript_sequences(
  x,
  genome_fasta = NULL,
  transcript_fasta = NULL,
  overwrite = FALSE,
  chunk_bytes = 6.4e+07
)

has_sequences(x)

transcript_sequences(x, transcript_id = NULL)

Arguments

x

An annotation directory path or an IsoformicExperiment.

genome_fasta

Path to a genome FASTA file (.fa, .fa.gz), see download_reference(file_type = "genome_fasta").

transcript_fasta

Path to a transcript FASTA file, see download_reference(file_type = "fasta").

overwrite

Logical, replace existing sequences (default FALSE).

chunk_bytes

Number of bytes read per chunk while streaming (default 64 MB).

transcript_id

Optional transcript identifiers to read; NULL reads all sequences.

Details

The sequences table is optional: annotation directories without it keep working, and has_sequences() tells whether it is present. Transcripts whose chromosome is absent from the FASTA (or whose identifier is absent from a transcript FASTA) are reported and left out.

Value

The path of the written Parquet file, invisibly. The table has columns transcript_id, sequence and seq_length.

See Also

transcript_orfs(), coding_potential()

Examples

gff <- system.file("extdata", "example.gff3", package = "isoformic")
fasta <- system.file("extdata", "example_transcripts.fa.gz", package = "isoformic")
annot <- prepare_isoformic_annotation(gff, output_path = tempdir(), annot_name = "seq_demo")
extract_transcript_sequences(annot, transcript_fasta = fasta, overwrite = TRUE)
has_sequences(annot)
head(transcript_sequences(annot)[, c("transcript_id", "seq_length")])

## Not run: 
# From a genome FASTA (covers novel transcripts of any annotation)
genome <- download_reference(version = "50", file_type = "genome_fasta", region = "primary")
extract_transcript_sequences(annot, genome_fasta = genome)

## End(Not run)

Read and cut the transcript trees of TreeTerminus

Description

TreeTerminus builds, from Salmon replicates, a forest of transcript trees: the leaves are transcripts and every internal node is the sum of the transcripts below it, built so that the inferential uncertainty falls as the tree is ascended. Unlike the flat groups of Terminus, a tree lets the resolution change from one isoform to the next: an isoform the reads determine stays a leaf, one they do not is replaced by the smallest node that they do determine.

  • read_treeterminus() reads the trees (Newick, one per line): cluster_nwk.txt for the trees of all samples (⁠treeterminus group --mean_inf true⁠), group_nwk.txt for one sample, or the output of ⁠treeterminus consensus⁠. TreeTerminus labels the leaves with the 0-based position of the transcript in quant.sf; salmon_dir (any of the Salmon directories, which share the order) or transcripts turns them into transcript IDs.

  • cut_transcript_trees() computes the inferential relative variance of every node from the replicates stored in an IsoformicExperiment (the draws of the transcripts below the node are summed), replaces every transcript whose own variance is at least cutoff by its lowest ancestor below cutoff, and returns the groups, which do not overlap (when two chosen nodes are nested, the larger one is kept). The result goes to add_uncertainty(groups = ), so that the confidence classes and collapse_groups work at the resolution the data support.

Transcripts whose whole path to the root stays above the cutoff are unresolved: by default they are left as they are (unresolved = "transcript"), where the confidence classes still flag them as uncertain; unresolved = "root" merges every tree that has one into a single group.

Usage

read_treeterminus(
  path,
  salmon_dir = NULL,
  transcripts = NULL,
  ignore_after_bar = TRUE
)

cut_transcript_trees(
  trees,
  x,
  cutoff = NULL,
  unresolved = c("transcript", "root")
)

Arguments

path

A Newick file of TreeTerminus, or a folder holding cluster_nwk.txt (or a single group_nwk.txt).

salmon_dir

A Salmon output directory quantified against the same index, whose quant.sf gives the order of the transcripts.

transcripts

Alternatively, the transcript names in quant.sf order.

ignore_after_bar

Logical. Keep only the part of transcript names before the first |.

trees

The result of read_treeterminus().

x

An IsoformicExperiment with inferential replicates (see add_uncertainty()).

cutoff

Inferential relative variance below which a node is well determined (the inf_rv_cutoff of add_uncertainty() by default).

unresolved

"transcript" or "root", see above.

Value

read_treeterminus(): a tibble with one row per node and leaf: tree_id, node_id (internal nodes; NA for leaves), transcript_id (leaves; NA for nodes) and parent_id (NA for the roots). cut_transcript_trees(): a tibble with transcript_id, group_id, group_size, group_inf_rv and tree_id for the transcripts that are grouped, with the cutoff in the cutoff attribute.

References

Singh NP, Love MI, Patro R (2023). TreeTerminus: creating transcript trees using inferential replicate counts. iScience 26(6):106961.

See Also

read_terminus_groups(), add_uncertainty()

Examples

nwk <- tempfile(fileext = ".txt")
writeLines(c("((0,1),2);", "(3,4);"), nwk)
read_treeterminus(nwk, transcripts = c("tA1", "tA2", "tA3", "tB1", "tB2"))

Transcript Type Color Palette

Description

Default colour palette for transcript types: the GENCODE/Ensembl biotypes used by the workflow, the gene level, generic labels for annotations without biotypes (unknown, novel) and the SQANTI3 structural categories assigned by add_sqanti_classification() to long-read transcript catalogs.

Usage

tx_type_palette()

Value

A named character vector of hexadecimal colours.

Examples

head(tx_type_palette())

Quantify and report the uncertainty of isoform-level results

Description

An isoform-level result is only as good as the quantification behind it. Reads that map to several isoforms of a gene can be shared out between them in more than one way, so the estimate of each isoform carries an inferential uncertainty that is unrelated to biological variability. Salmon measures it by drawing replicates from the posterior (Gibbs sampling, --numGibbsSamples) and by writing the equivalence classes (--dumpEq). These functions turn that information into columns that can be filtered on and reported.

Every isoform gets four kinds of evidence:

  • Quantification uncertainty: the inferential relative variance (mean_inf_rv, Zhu et al. 2019, as in fishpond), the variance of the replicates in excess of what counting noise alone would give, relative to the expression. Isoforms with a high value are not well determined by the reads. uncertain flags mean_inf_rv >= inf_rv_cutoff.

  • Ambiguity between isoforms: the correlation between the replicates of isoforms of the same gene. A strong negative correlation means the reads cannot tell the two isoforms apart and every read taken from one is given to the other. Pairs at or below cor_cutoff are ambiguous and are joined into ambiguity_groups that can be tested as one feature. This is the idea of mmcollapse (Turro et al. 2014), with a fixed cutoff.

  • Read support: the share of the fragments of an isoform that map to it alone (unique_fraction, from the equivalence classes).

  • Stability of the fold-change: the contrast between two groups is repeated on every replicate. lfc_lo/lfc_hi is the 95% interval of the log2 fold-change over replicates, sign_agreement the share of replicates that agree on its direction and frac_draws_sig the share in which the isoform is called differentially expressed.

de_confidence() combines the last three into one class per isoform: high when the fold-change is stable (sign_agreement >= min_agreement), the isoform is not uncertain and has no ambiguous sibling; moderate when exactly one of these fails; low when two or more fail. After add_uncertainty(identifiability = TRUE) a fourth condition counts: the equivalence classes must identify the isoform (identifiable). The class says how far a call on the isoform can be trusted, so read it for the isoforms flagged by the primary test (n_det_sig, confident_de): an isoform without a real change is moderate or low simply because its fold-change is not stable.

  • add_uncertainty(x, paths) reads the replicates, equivalence classes and run metadata from the Salmon output directories paths (named by sample ID, in any order), computes the tables below and stores them in the object, so that they are written by write_isoformic(). When group is given it also stores the fold-change stability of that contrast.

  • tx_uncertainty(x): per-transcript table, for the transcripts whose draws are in the object (the expressed ones).

  • isoform_ambiguity(x): per-pair table of replicate correlations.

  • de_confidence(x, group): per-feature table of fold-change stability and confidence class; with collapse_groups = TRUE, ambiguous isoforms are summed into one feature before testing.

  • uncertainty_report(x): a list of summary tables for a methods or results section.

  • uncertainty_methods(x): a ready-to-edit paragraph that states the settings used.

The replicates themselves are kept in memory only (in metadata(x)$inf_reps) and are not written by write_isoformic(); the tables derived from them are. Draws are kept for the transcripts with an estimated mean count of at least min_count; the others are treated as unexpressed.

Usage

add_uncertainty(
  self,
  paths = NULL,
  group = NULL,
  levels = NULL,
  n_draws = NULL,
  min_count = 1,
  inf_rv_cutoff = 0.5,
  cor_cutoff = -0.5,
  min_agreement = 0.95,
  equivalence = TRUE,
  identifiability = FALSE,
  run_qc = TRUE,
  keep_draws = TRUE,
  collapse_groups = FALSE,
  groups = NULL,
  ...
)

tx_uncertainty(self, gene_name = NULL, ...)

isoform_ambiguity(self, gene_name = NULL, ambiguous_only = FALSE, ...)

de_confidence(
  self,
  group = NULL,
  levels = NULL,
  collapse_groups = FALSE,
  gene_name = NULL,
  pseudocount = 5,
  inf_rv_cutoff = NULL,
  min_agreement = NULL,
  ...
)

uncertainty_report(self, ...)

uncertainty_methods(self, ...)

Arguments

self

An IsoformicExperiment.

paths

Salmon output directories (see read_inferential_replicates()), named by sample ID. NULL uses the replicates already stored in the object.

group

Name of a col_data() column with the sample groups.

levels

The two group levels to contrast, reference first. Samples of other groups are left out of the contrast. NULL uses the levels of group, which must then be exactly two.

n_draws

Number of replicates to read; NULL reads all of them.

min_count

Minimum mean estimated count for a transcript to be assessed.

inf_rv_cutoff

Inferential relative variance from which an isoform is called uncertain. NULL uses the value the tables were computed with.

cor_cutoff

Mean replicate correlation at or below which two isoforms of a gene are called ambiguous: a number, or "adaptive" to derive it from the data as mmcollapse does (minus the 97.5th percentile of the largest mean correlation of each isoform, which treats the positive correlations as noise). The value used is stored and stated by uncertainty_methods().

min_agreement

Share of replicates that must agree on the direction of a fold-change for it to be called stable. NULL uses the stored value.

equivalence

Logical, read the equivalence classes when present, or the table returned by equivalence_support(), to attach read support when the draws are supplied without paths.

identifiability

Logical, also compute which transcripts the equivalence classes can tell apart (equivalence_identifiability(); minutes per sample, needs paths and, for human samples, the Matrix package), or the table that function returned. de_confidence() then counts a non-identifiable transcript as one more reason against the call.

run_qc

Logical, add the Salmon run metadata (see salmon_run_qc()) to col_data().

keep_draws

Logical, keep the replicates in the object (needed to recompute the tables and for productive_fraction() uncertainty).

collapse_groups

Logical, sum ambiguous isoforms into one feature before testing the contrast.

groups

External groups of transcripts that the reads cannot tell apart, replacing the groups built from the correlation of the replicates: a table with transcript_id and group_id, or the path to Terminus output (see read_terminus_groups()), or the cut of TreeTerminus trees (see cut_transcript_trees()). The confidence classes and collapse_groups then follow these groups; the pairs of isoform_ambiguity() keep describing the correlation.

...

Unused.

gene_name

Optional gene names or IDs to keep.

ambiguous_only

Logical, isoform_ambiguity() returns only the ambiguous pairs.

pseudocount

Pseudocount of the log2 fold-change (5, as in swish).

Details

The thresholds are heuristics, not universal constants: inf_rv_cutoff (0.5), cor_cutoff (-0.5) and min_agreement (0.95) are conservative starting points. With 30 draws, sampling noise alone puts the inferential relative variance of a well-determined, highly expressed transcript near 0.1, so cutoffs much below 0.5 flag noise; poorly determined isoforms typically reach values of several units. Report the numbers next to the classes, and rerun with other cutoffs if the data call for it. The replicates measure the uncertainty of the quantification only; they do not replace biological replicates and cannot make a noisy contrast significant.

What is not measured. The replicates describe how much an estimate moves under the quantification model. They do not find the transcripts whose abundance is not identifiable, that is, where several abundance vectors explain the reads equally well (Zheng et al. 2022 report that only about half of the transcripts flagged by replicate variance are also non-identifiable in that sense), and they do not find an estimate that is wrong because the annotation lacks the transcript the reads came from (Ma and Kingsford 2019). An ambiguous pair is a statement about the replicates, not a proof of non-identifiability.

How many replicates. The inferential relative variance and the correlations are computed per sample, from the replicates of that sample. The overdispersion used to scale counts (see inferential_overdispersion()) pools all samples, and its precision depends on the total n_samples * (n_replicates - 1): Baldoni, Chen and Smyth (2024) recommend at least 60 and prefer 200 to 300, and find that Gibbs samples resolve low counts better than bootstrap replicates. add_uncertainty() says so when the total is below 60.

Fold-changes are computed on counts scaled to a common library size, as log2(mean_b + pseudocount) - log2(mean_a + pseudocount) with a pseudocount of 5 (the swish convention), and the per-replicate test is a Welch t-test on the log scale with Benjamini-Hochberg adjustment across features. This is a screening statistic for stability, not a replacement for the primary test (swish, DESeq2, ...), whose results are shown next to it. When the sample table (col_data) has a library_size column, with the total estimated count of the full quantification, it is used for the scaling. Set it when the object holds only a subset of the transcripts, so that the subset does not change the scaling.

Value

  • add_uncertainty(): the object with dea$uncertainty, dea$ambiguity and, when group is given, dea$confidence filled in.

  • tx_uncertainty(): a tibble with transcript_id, gene_id, names and type, mean_count, mean_inf_rv, max_inf_rv, mean_inf_cv, uncertain, min_sibling_cor, n_ambiguous_partners, ambiguity_group and, when equivalence classes were read, n_classes, n_unique_fragments, unique_fraction and low_information (TRUE for an uncertain isoform without a single fragment of its own, the isoforms mmcollapse selects for collapsing). With identifiability, also identifiable_fraction and identifiable.

  • isoform_ambiguity(): a tibble of isoform pairs of the same gene with mean_cor, min_cor, n_samples, collapse_gain and ambiguous. collapse_gain is the score Terminus groups on (Sarkar et al. 2020): the inferential relative variance of the sum of the two isoforms minus the mean of their own, averaged over samples. The more negative, the more is gained by testing the pair as one feature.

  • de_confidence(): a tibble with one row per feature: feature_id, feature_type ("transcript" or "group"), gene and transcript names, the interval and stability of the fold-change, mean_inf_rv, ambiguous, identifiable (only when the identifiability was computed; NA for groups), confidence (an ordered factor), reason, the existing differential expression result (det_log2FC, det_qvalue, n_det_sig) and confident_de, which is TRUE when a significant isoform has high confidence.

  • uncertainty_report(): a list with settings, replicates (replicate type, number of draws, degrees of freedom over the study and, when the draws are in the object, the median overdispersion, which is close to 1 for long reads), run, transcripts (by transcript type), genes, de and switches tibbles.

  • uncertainty_methods(): a character string.

References

Zhu, A., Srivastava, A., Ibrahim, J.G., Patro, R., Love, M.I. (2019). Nonparametric expression analysis using inferential replicate counts. Nucleic Acids Research 47(18), e105.

Sarkar, H., Srivastava, A., Bravo, H.C., Love, M.I., Patro, R. (2020). Terminus enables the discovery of data-driven, robust transcript groups from RNA-seq data. Bioinformatics 36(Suppl 1), i102-i110.

Turro, E., Astle, W.J., Tavare, S. (2014). Flexible analysis of RNA-seq data using mixed effects models. Bioinformatics 30(2), 180-188.

Zheng, H., Ma, C., Kingsford, C. (2022). Deriving ranges of optimal estimated transcript expression due to nonidentifiability. Journal of Computational Biology 29(2), 121-139.

Ma, C., Kingsford, C. (2019). Detecting, categorizing, and correcting coverage anomalies of RNA-seq quantification. Cell Systems 9(6), 589-599.

Baldoni, P.L., Chen, L., Smyth, G.K. (2024). Faster and more accurate assessment of differential transcript expression with Gibbs sampling and edgeR v4. NAR Genomics and Bioinformatics 6(4), lqae151.

See Also

read_inferential_replicates(), plot_de_confidence(), isoform_switches()

Examples

quant_dirs <- list.files(
  system.file("extdata", "mini_quants", package = "isoformic"),
  full.names = TRUE
)
names(quant_dirs) <- sub("_quant$", "", basename(quant_dirs))
annot <- system.file("extdata", "mini_annotation", package = "isoformic")
col_data <- data.frame(
  sample_id = names(quant_dirs),
  condition = rep(c("control", "treatment"), each = 3)
)
iso <- read_salmon(quant_dirs, annot_path = annot, col_data = col_data)

# With your own data, `read_salmon(dirs, annot, inferential = TRUE)` or
# `add_uncertainty(iso, paths = dirs)` read the replicates that
# `salmon quant --numGibbsSamples 30` wrote; here bundled draws are used
draws <- as_inferential_replicates(read_parquet(
  system.file("extdata", "mini_draws.parquet", package = "isoformic")
))
iso@metadata$inf_reps <- draws
iso <- add_uncertainty(iso, group = "condition")
head(tx_uncertainty(iso))
isoform_ambiguity(iso, ambiguous_only = TRUE)
head(de_confidence(iso))
uncertainty_report(iso)$transcripts

Plot the uncertainty of isoform-level results

Description

  • plot_de_confidence(x, gene_name) shows, for the isoforms of the given genes, the median log2 fold-change over the Salmon replicates with its 95% interval, coloured by the confidence class of de_confidence() and with the shape marking the calls of the primary differential expression test. An interval that crosses zero, a faded colour or an ambiguous isoform tell the reader not to trust the call.

  • plot_isoform_correlation(x, gene_name) draws the correlation between the replicates of every pair of isoforms of a gene. Strongly negative cells (outlined when ambiguous) mark isoforms whose reads cannot be told apart.

  • plot_inf_rv(x) shows the distribution of the inferential relative variance per transcript type with the cutoff used to call isoforms uncertain.

  • confidence_palette() gives the colours of the confidence classes.

Usage

confidence_palette()

plot_de_confidence(self, gene_name, ncol = 1L, ...)

plot_isoform_correlation(self, gene_name, ncol = 1L, ...)

plot_inf_rv(self, top_types = 6L, ...)

Arguments

self

An IsoformicExperiment with uncertainty tables (see add_uncertainty()).

gene_name

Gene names or IDs to plot.

ncol

Number of panel columns.

...

Unused.

top_types

Number of the most frequent transcript types to show.

Value

A ggplot object, or a named character vector for confidence_palette().

See Also

add_uncertainty(), de_confidence()