| 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 |
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().
add_annotation_columns( x, table, level = c("transcript", "gene"), by = NULL, prefix = NULL )add_annotation_columns( x, table, level = c("transcript", "gene"), by = NULL, prefix = NULL )
x |
An annotation directory path or an IsoformicExperiment. |
table |
A data frame, or a path to a tabular file readable by
|
level |
|
by |
Name of the key column in |
prefix |
Optional prefix added to the new column names. |
The annotation directory path, invisibly.
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)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)
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().
add_fantom_cat_tables(x, id_mapping, gene_info = NULL)add_fantom_cat_tables(x, id_mapping, gene_info = NULL)
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. |
The annotation directory path, invisibly.
## 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)## 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)
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().
add_sqanti_classification(x, classification, overwrite_types = TRUE)add_sqanti_classification(x, classification, overwrite_types = TRUE)
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
|
overwrite_types |
Logical. Replace existing transcript types
(default |
The annotation directory path, invisibly.
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)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)
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.
build_coding_model( coding_cds, coding, noncoding, output_dir, min_orf_length = 90L, pseudocount = 1 )build_coding_model( coding_cds, coding, noncoding, output_dir, min_orf_length = 90L, pseudocount = 1 )
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 |
min_orf_length |
Minimum ORF length used when scoring the training sequences. |
pseudocount |
Pseudocount added to hexamer counts. |
A list with the hexamer table, the fitted glm and the training
accuracy, invisibly.
## Not run: build_coding_model(cds_sequences, mrna_sequences, lncrna_sequences, output_dir = "coding_model") ## End(Not run)## Not run: build_coding_model(cds_sequences, mrna_sequences, lncrna_sequences, output_dir = "coding_model") ## End(Not run)
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).
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)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)
output_path |
Directory receiving the Parquet file (default: the frozen-data cache). |
sources_dir |
Directory holding (or receiving) the source files;
default: |
The path of the written Parquet file, invisibly.
## Not run: build_frozen_riboseq_orfs() ## End(Not run)## Not run: build_frozen_riboseq_orfs() ## End(Not run)
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().
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, ...)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, ...)
self |
|
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 ( |
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.
Tibbles, or the modified object for replacement functions.
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")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")
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.
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, ... )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, ... )
self |
|
assay |
Name of the transcript assay to use (default |
... |
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 |
levels |
Levels of |
confident_only |
Logical. Count only the significant isoforms with
high confidence (see |
A matrix for isoform_fraction(), tibbles otherwise.
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"))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"))
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.
domain_retention(self, gene_name = NULL, domains = NULL, ...)domain_retention(self, gene_name = NULL, domains = NULL, ...)
self |
|
gene_name |
Optional genes (names or IDs) to restrict the result to. |
domains |
Data frame or Parquet path of the domain table; |
... |
Passed on to methods. |
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).
## Not run: iso <- example_isoformic() domain_retention(iso, gene_name = "RBPJ") ## End(Not run)## Not run: iso <- example_isoformic() domain_retention(iso, gene_name = "RBPJ") ## End(Not run)
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.
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" )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" )
level |
FANTOM CAT level: |
tables |
Which tables to download. |
output_path |
Directory where the file is saved. Defaults to
|
timeout_limit |
Maximum time in seconds for the download. Takes
precedence over |
method |
Method used by |
A named character vector of file paths (id_mapping,
gene_info, cage_clusters).
## Not run: tables <- download_fantom_cat_tables("lv3_robust") tables ## End(Not run)## Not run: tables <- download_fantom_cat_tables("lv3_robust") tables ## End(Not run)
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.
download_hprc_annotation( sample, haplotype = c(1L, 2L), assembly = c("chm13", "hg38"), output_path = ":cache:", timeout_limit = 3600, method = "auto" )download_hprc_annotation( sample, haplotype = c(1L, 2L), assembly = c("chm13", "hg38"), output_path = ":cache:", timeout_limit = 3600, method = "auto" )
sample |
HPRC sample ID, for example |
haplotype |
Haplotype numbers to download, |
assembly |
Coordinate space of the CAT run: |
output_path |
Directory where the file is saved. Defaults to
|
timeout_limit |
Maximum time in seconds for the download. Takes
precedence over |
method |
Method used by |
A named character vector of file paths (names hap1, hap2),
ready for merge_annotations().
## Not run: files <- download_hprc_annotation("HG00438") merged <- merge_annotations(files, annot_name = "HG00438_chm13") merged ## End(Not run)## Not run: files <- download_hprc_annotation("HG00438") merged <- merge_annotations(files, annot_name = "HG00438_chm13") merged ## End(Not run)
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().
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" )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" )
version |
Release version. GENCODE: the release number ( |
reference |
One of |
organism |
|
file_type |
|
region |
Annotation flavour: |
species |
Ensembl species name in lower snake case
( |
division |
Ensembl division: |
accession |
NCBI assembly accession ( |
mane_source |
Identifier space of MANE files: |
output_path |
Directory where the file is saved. Defaults to
|
timeout_limit |
Maximum time in seconds for the download. Takes
precedence over |
method |
Method used by |
The full path to the downloaded (or already present) file.
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).
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.
## 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)## 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)
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.
download_reference_url( url, output_path = ":cache:", file_name = NULL, timeout_limit = 3600, method = "auto" )download_reference_url( url, output_path = ":cache:", file_name = NULL, timeout_limit = 3600, method = "auto" )
url |
URL of the file. |
output_path |
Directory where the file is saved; |
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 |
method |
Method used by |
The full path to the file.
## 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)## 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)
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.
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 )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 )
self |
An IsoformicExperiment or a transcript-level DE table. |
genesets_list |
Named list of character vectors (gene symbols), as
returned by |
tx_to_gene |
Data frame with |
pval_cutoff |
Keep pathways with |
tx_types |
Named list defining the transcript categories to test.
Defaults to |
min_size, max_size
|
Minimum and maximum gene set size passed to
|
rank_by |
Statistic that ranks the transcripts: |
... |
Passed on to |
annotation_types |
Transcript types present in the annotation,
used to choose between |
path |
Path to a GMT file. |
enrichment_df |
Result of |
n |
Number of top pathways (by adjusted p-value) to show. |
experiments |
Categories to show; |
nes_cutoff |
Minimum absolute NES to show. |
strip_prefix |
Regular expression removed from pathway names before
plotting (default drops MSigDB collection prefixes such as |
label_width |
Pathway labels are wrapped to this many characters. |
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.
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.
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.
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) }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) }
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).
equivalence_identifiability( paths, transcripts = NULL, ignore_after_bar = TRUE, max_dense = 400L, max_iterations = 50000L )equivalence_identifiability( paths, transcripts = NULL, ignore_after_bar = TRUE, max_dense = 400L, max_iterations = 50000L )
paths |
Character vector of Salmon output directories (containing
|
transcripts |
Optional transcript IDs to keep. Reading every
transcript of a human annotation for many samples takes gigabytes of
memory, so |
ignore_after_bar |
Logical. Keep only the part of transcript names
before the first |
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
|
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:
A class with a single unresolved transcript resolves it (a class of one transcript does so directly); repeated until nothing changes.
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.
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.
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).
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
equivalence_support() for the share of unique fragments,
add_uncertainty() for the uncertainty measured by the posterior draws.
# 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))# 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))
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.
example_isoformic()example_isoformic()
iso <- example_isoformic() isoiso <- example_isoformic() iso
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.
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 )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 )
release_tag |
Tag of the GitHub release hosting the frozen files. |
zenodo_record |
Zenodo record id (or |
name |
Dataset name, one of |
output_path |
Directory holding the frozen files; |
build |
|
verify |
Logical, check the MD5 of the file against the registry
(default |
mirrors |
Character vector of base URLs tried in order for the
frozen file; default |
... |
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 |
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.
frozen_datasets()[, c("name", "version", "file")] ## Not run: appris <- read_frozen_data("appris") head(appris) ## End(Not run)frozen_datasets()[, c("name", "version", "file")] ## Not run: appris <- read_frozen_data("appris") head(appris) ## End(Not run)
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.
get_isoformic_cache(..., ext = NULL)get_isoformic_cache(..., ext = NULL)
... |
Additional path components to append to the cache directory. |
ext |
An optional file extension (e.g., "rds", "csv") to append to the final path. |
This function uses the [tools::R_user_dir()] function to determine the
user cache directory.
A path character string representing the path to the user cache
directory for the isoformic package.
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.
gtex_reference(self, tissue, gtex = NULL, include_altered = TRUE, ...) gtex_tissues(gtex = NULL)gtex_reference(self, tissue, gtex = NULL, include_altered = TRUE, ...) gtex_tissues(gtex = NULL)
self |
|
tissue |
GTEx tissue name ( |
gtex |
Data frame or Parquet path of the GTEx table; |
include_altered |
Logical, count |
... |
Passed on to methods. |
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.
## Not run: iso <- example_isoformic() ref <- gtex_reference(iso, tissue = "Whole Blood") productive_fraction(iso, group = "condition", reference = ref) ## End(Not run)## Not run: iso <- example_isoformic() ref <- gtex_reference(iso, tissue = "Whole Blood") productive_fraction(iso, group = "condition", reference = ref) ## End(Not run)
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.
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")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")
paths |
Character vector of Salmon output directories (containing
|
transcripts |
Optional transcript IDs to keep. Reading every
transcript of a human annotation for many samples takes gigabytes of
memory, so |
n_draws |
Number of replicates to keep (the first ones). |
ignore_after_bar |
Logical. Keep only the part of transcript names
before the first |
min_percent_mapped |
Samples below this mapping rate (percent) get the
|
reps |
A list of transcript x sample count matrices, one per replicate. |
table |
A long table with |
samp_type |
Replicate type recorded on the result, |
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.
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")]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")]
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.
inferential_overdispersion(self, prior_df = 3, ...) scale_counts(self, assay = "counts", name = paste0(assay, "_scaled"), ...)inferential_overdispersion(self, prior_df = 3, ...) scale_counts(self, assay = "counts", name = paste0(assay, "_scaled"), ...)
self |
An IsoformicExperiment with inferential replicates (see
|
prior_df |
Degrees of freedom of the prior (3 in |
... |
Unused. |
assay |
Name of the counts assay to scale. |
name |
Name of the new assay. |
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.
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.
add_uncertainty(), de_confidence()
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))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))
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.
is_deg_sig(deg_sig_vector, det_table)is_deg_sig(deg_sig_vector, det_table)
deg_sig_vector |
Character vector of transcript names (or IDs) belonging to significantly differentially expressed genes. |
det_table |
Transcript-level table with a |
det_table with an extra DEG_sig column.
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)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)
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).
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"), ...)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"), ...)
x |
A |
annot_path |
Annotation directory or GFF3/GTF file. |
col_data |
Sample metadata; taken from |
experiment_name |
Optional experiment name. |
ignore_after_bar |
Logical, truncate GENCODE |
drop_unannotated |
Logical, drop transcripts absent from the annotation instead of failing. |
self |
|
level |
|
... |
Passed on to methods. |
as_isoformic() returns an IsoformicExperiment;
as_summarized_experiment() returns a SummarizedExperiment.
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 }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 }
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()).
write_isoformic( self, path = NULL, overwrite = FALSE, copy_annotation = FALSE, ... ) read_isoformic(path, annot_path = NULL)write_isoformic( self, path = NULL, overwrite = FALSE, copy_annotation = FALSE, ... ) read_isoformic(path, annot_path = NULL)
self |
|
path |
Directory to write to or read from. For |
overwrite |
Logical, replace an existing directory. |
copy_annotation |
Logical, copy the annotation directory inside
|
... |
Passed on to methods. |
annot_path |
Optional annotation directory overriding the stored one when reading. |
write_isoformic() returns the object with data_path set,
invisibly. read_isoformic() returns an IsoformicExperiment.
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))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))
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.
isoformic.frozen_mirrorsCharacter 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_cacheFALSE 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).
timeoutTimeout 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_interactiveOverrides 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.
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.
LOCALAPPDATAOn 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.
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.
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_CPUSNumber of parallel testthat workers used by
just test.
NOT_CRANSet 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.
get_isoformic_cache(), frozen_data, download_reference()
# 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") )# 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 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().
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 )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 )
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 |
col_data |
Data frame of sample metadata with a |
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. |
An IsoformicExperiment object.
experiment_nameSingle string. Generated when not supplied.
annot_pathPath to the annotation directory, or NULL for an
empty object.
data_pathDirectory the object was written to or read from
(see write_isoformic()), or NULL.
assaysNamed list of transcript-level matrices.
gene_assaysNamed list of gene-level matrices. Derived from
assays when not set explicitly.
col_dataTibble of sample metadata; its sample_id column
matches the assay column names.
deaList with differential expression results: det
(transcripts), deg (genes) and cutoffs. Use de_tx<- and
de_gene<- to set them.
gseaNamed list of enrichment result tables.
metadataFree-form named list.
annot_metadataNamed list describing the annotation source, read from the annotation directory unless set explicitly.
tx_type_paletteNamed 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.
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.
example_isoformic() for a ready-made object,
read_salmon() and as_isoformic() to create one from quantifications,
IsoformicExperiment-accessors for the accessor generics.
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")) ) smalliso <- 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
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).
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, ...)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, ...)
self |
|
... |
Passed on to methods. |
value |
Replacement value. |
name |
Name of the 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. |
See the individual descriptions above.
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"))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"))
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.
join_DEG_DET( deg_table, det_table, logfc_cut = 1, pval_cut = 0.05, use_fdr = FALSE, transcript_types = default_transcript_types() )join_DEG_DET( deg_table, det_table, logfc_cut = 1, pval_cut = 0.05, use_fdr = FALSE, transcript_types = default_transcript_types() )
deg_table |
Gene-level results with |
det_table |
Transcript-level results with |
logfc_cut |
Absolute log2 fold-change cutoff for significance. |
pval_cut |
P-value cutoff for significance. Like the cutoffs of
|
use_fdr |
Logical, test the |
transcript_types |
Transcript types to keep. |
A tibble with feature_id, feature_name, feature_type,
gene_name, log2FC, pvalue (and qvalue when present) and is_de.
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)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)
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.
make_tx_to_gene( file_path, file_type = c("auto", "fasta", "gff", "gtf"), output_path = NULL )make_tx_to_gene( file_path, file_type = c("auto", "fasta", "gff", "gtf"), output_path = NULL )
file_path |
Path to a FASTA ( |
file_type |
|
output_path |
Passed to |
With an IsoformicExperiment object, use tx_to_gene() or tx_annot(),
which read the same information from the annotation directory.
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.
gff <- system.file("extdata", "example.gff3", package = "isoformic") tx2gene <- make_tx_to_gene(gff, output_path = tempdir()) head(tx2gene)gff <- system.file("extdata", "example.gff3", package = "isoformic") tx2gene <- make_tx_to_gene(gff, output_path = tempdir()) head(tx2gene)
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.
merge_annotations( annot_paths, output_path = NULL, annot_name = "merged_haplotypes", id_suffix = TRUE, overwrite = FALSE )merge_annotations( annot_paths, output_path = NULL, annot_name = "merged_haplotypes", id_suffix = TRUE, overwrite = FALSE )
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. |
annot_name |
Name of the merged annotation directory. |
id_suffix |
Logical. Append |
overwrite |
Logical. Replace an existing merged directory. |
The path to the merged annotation directory.
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)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)
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.
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"), ... )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"), ... )
path |
Path to the file to read or write. |
columns |
Optional character vector of columns to read.
|
n_max |
Maximum number of rows to read. |
... |
Reserved for future use; must be empty. |
x |
A data frame (or tibble) to write. |
compression |
Parquet compression codec. |
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.
read_parquet() and read_tabular() return a tibble.
write_parquet() returns path, invisibly.
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)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)
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.
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, ...)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, ...)
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; |
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 |
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 |
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 |
A ggplot object.
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"))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"))
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().
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 )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 )
self |
An IsoformicExperiment or a long DE table. |
feature |
Character vector of gene names (or IDs, or transcript
names, matched against |
feature_column |
Column of the DE table used to select features
(default |
color_palette |
Named colour vector per transcript type; defaults
to the object's palette or |
ncol |
Number of facet columns, |
... |
Passed on to methods. |
de_data |
A long DE table (see |
A ggplot object.
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")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")
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.
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, ... )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, ... )
self |
An IsoformicExperiment; for |
gene_name |
Optional genes (names or IDs) to restrict the result to. |
polya_atlas |
|
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; |
path |
Path to a GENCODE |
group |
Name of a |
levels |
Levels of |
assay |
Transcript assay to use ( |
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 |
min_size, max_size
|
Minimum and maximum gene set size passed to
|
rank_by |
Statistic that ranks the genes in |
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.
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)) }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)) }
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.
prepare_annotation( file_path, file_type = c("auto", "gff", "gtf"), output_path = NULL )prepare_annotation( file_path, file_type = c("auto", "gff", "gtf"), output_path = NULL )
file_path |
Path to an annotation directory or to a GFF3/GTF file. |
file_type |
Passed to |
output_path |
Passed to |
A named list with tibbles genes, transcripts, exons,
seq_regions and a named list metadata.
gff <- system.file("extdata", "example.gff3", package = "isoformic") annot <- prepare_annotation(gff, output_path = tempdir()) names(annot) head(annot$genes)gff <- system.file("extdata", "example.gff3", package = "isoformic") annot <- prepare_annotation(gff, output_path = tempdir()) names(annot) head(annot$genes)
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.
prepare_exon_annotation( gene_name, file_path, file_type = c("auto", "gff", "gtf"), output_path = NULL )prepare_exon_annotation( gene_name, file_path, file_type = c("auto", "gff", "gtf"), output_path = NULL )
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 |
output_path |
Passed to |
A tibble with columns gene_id, gene_name, transcript_id,
transcript_name, transcript_type, exon_id, exon_number, seqid,
start_pos, end_pos, strand.
gff <- system.file("extdata", "example.gff3", package = "isoformic") exons <- prepare_exon_annotation("RBPJ", gff, output_path = tempdir()) head(exons)gff <- system.file("extdata", "example.gff3", package = "isoformic") exons <- prepare_exon_annotation("RBPJ", gff, output_path = tempdir()) head(exons)
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.
prepare_isoformic_annotation( input_path, output_path = NULL, file_type = c("auto", "gff", "gtf"), annot_name = NULL, overwrite = FALSE, haplotype = NULL )prepare_isoformic_annotation( input_path, output_path = NULL, file_type = c("auto", "gff", "gtf"), annot_name = NULL, overwrite = FALSE, haplotype = NULL )
input_path |
Path to a GFF3 or GTF file, optionally gzip-compressed. |
output_path |
Directory under which the annotation directory is
created. |
file_type |
|
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 |
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.
The path to the annotation directory (character string).
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")))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")))
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.
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 )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 )
txi_transcript |
Transcript expression: a matrix or data frame with
transcript IDs as row names or in a |
sample_metadata |
Data frame whose first column (or |
tx_to_gene |
Data frame with |
de_result_gene |
Gene-level results with |
de_result_transcript |
Transcript-level results with
|
var |
Name of the grouping column in |
var_levels |
Levels of |
txi_gene |
Optional gene expression table (same formats as
|
gene_name |
Optional genes to keep (names or IDs); |
pvalue_cutoff, lfc_cutoff, use_fdr
|
Significance cutoffs. |
A tibble in the format described in profile_data().
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)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)
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.
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, ...)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, ...)
self |
An IsoformicExperiment. |
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 |
use_sequence |
Logical, use the sequence-derived ORFs of
|
use_evidence |
Logical, apply the evidence columns (default |
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 |
group |
Name of a |
levels |
Levels of |
assay |
Transcript assay to use (default |
include_altered |
Logical, count |
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); |
reference |
Optional tibble from |
genesets_list |
Named list of gene symbol vectors (see |
min_size, max_size
|
Gene set size limits passed to |
rank_by |
Statistic that ranks the genes in
|
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().
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)$summaryiso <- 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
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).
add_appris(x, table = NULL) add_riboseq_orfs(x, table = NULL) add_nmd_exons(x, table = NULL)add_appris(x, table = NULL) add_riboseq_orfs(x, table = NULL) add_nmd_exons(x, table = NULL)
x |
An annotation directory path or an IsoformicExperiment. |
table |
A data frame with the dataset, or a path to its Parquet
file; |
The annotation directory path, invisibly.
## 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)## 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)
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.
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, ... )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, ... )
self |
An IsoformicExperiment, or (for |
gene_name |
Character vector of gene names or IDs to profile. |
group |
Name of the |
levels |
Levels of |
assay |
Name of the transcript assay to summarise (default
|
... |
Passed on to methods. |
log_scale |
Logical, show |
label |
Logical, label features at the last group level. |
ncol |
Number of facet columns, |
color_palette |
Named colour vector per transcript type; defaults
to the object's palette or |
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.
iso <- example_isoformic() head(profile_data(iso, gene_name = "RBPJ", group = "condition")) plot_tx_expr(iso, gene_name = c("RBPJ", "EGFR"), group = "condition")iso <- example_isoformic() head(profile_data(iso, gene_name = "RBPJ", group = "condition")) plot_tx_expr(iso, gene_name = c("RBPJ", "EGFR"), group = "condition")
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().
read_oarfish( paths, annot_path, col_data = NULL, experiment_name = NULL, ignore_after_bar = TRUE, drop_unannotated = FALSE, inferential = FALSE )read_oarfish( paths, annot_path, col_data = NULL, experiment_name = NULL, ignore_after_bar = TRUE, drop_unannotated = FALSE, inferential = FALSE )
paths |
Output prefixes of Oarfish (the value of |
annot_path |
Annotation directory or GFF3/GTF file (see
|
col_data |
Optional data frame of sample metadata whose first column
(or a |
experiment_name |
Optional experiment name. |
ignore_after_bar |
Logical. Keep only the part of transcript names
before the first |
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 |
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.
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))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))
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.
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 )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 )
path |
The output prefix of Oarfish (the value of |
ignore_after_bar |
Logical. Keep only the part of transcript names
before the first |
cells |
A data frame with a |
annot_path |
Annotation directory or GFF3/GTF file (see
|
col_data |
Optional sample metadata with a |
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. |
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.
read_oarfish_sc_counts(): a tibble with barcode,
transcript_id and count. read_oarfish_sc(): an IsoformicExperiment.
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)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)
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()).
read_salmon( paths, annot_path, col_data = NULL, experiment_name = NULL, ignore_after_bar = TRUE, drop_unannotated = FALSE, inferential = FALSE )read_salmon( paths, annot_path, col_data = NULL, experiment_name = NULL, ignore_after_bar = TRUE, drop_unannotated = FALSE, inferential = FALSE )
paths |
Character vector of Salmon output directories (containing
|
annot_path |
Annotation directory or GFF3/GTF file (see
|
col_data |
Optional data frame of sample metadata whose first column
(or a |
experiment_name |
Optional experiment name. |
ignore_after_bar |
Logical. Keep only the part of transcript names
before the first |
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 |
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().
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) isoquant_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
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:
read_terminus_groups(path, ignore_after_bar = TRUE)read_terminus_groups(path, ignore_after_bar = TRUE)
path |
The |
ignore_after_bar |
Logical. Keep only the part of transcript names
before the first |
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.
A tibble with group_id, transcript_id and group_size.
add_uncertainty(), isoform_ambiguity()
clusters <- tempfile(fileext = ".txt") writeLines( c( "NewTr1,ENST00000831217.1,ENST00000831165.1", "NewTr2,ENST00000831423.1,ENST00000831157.1,ENST00000831246.1" ), clusters ) read_terminus_groups(clusters)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() 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.
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" )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" )
paths |
Salmon output directories (or paths to their |
output_dir |
Folder for the Terminus output; one subfolder per sample
holds |
consensus_thresh |
Share of samples in which two transcripts must be
grouped for the consensus to group them ( |
min_spread |
Minimum spread of a transcript for its edges to be
collapse candidates ( |
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 |
env_name |
Name of the conda environment with Terminus. |
verbose |
Passed to |
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.
The consensus groups, as returned by read_terminus_groups(),
with the output folder in the output_dir attribute.
read_terminus_groups(), add_uncertainty(), salmon_quant()
## 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)## 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)
Create a Salmon index from a reference transcriptome FASTA file.
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 )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 )
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 |
decoy_fasta |
Optional path to a FASTA file containing decoy sequences
(default is |
clip_poly_a |
Logical indicating whether to clip poly-A tails
(default is |
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.
processx style output list.
Perform transcript quantification using Salmon's selective-alignment-based mode from raw RNA-seq reads.
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" )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" )
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 |
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"). |
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.
processx style output list.
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".
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"), ... )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"), ... )
x |
An annotation directory path or an IsoformicExperiment. |
genome_fasta |
Path to a genome FASTA file ( |
overwrite |
Logical, replace an existing table (default |
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 |
|
... |
Unused. |
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.
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.
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.
extract_transcript_sequences(), transcript_productivity()
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)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)
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.
summarize_to_gene(x, tx_to_gene)summarize_to_gene(x, tx_to_gene)
x |
A numeric matrix (transcripts in rows) or a named list of such matrices sharing row names. |
tx_to_gene |
Data frame with |
A matrix, or a named list of matrices, with genes in rows.
iso <- example_isoformic() g <- summarize_to_gene(assay(iso, "abundance"), tx_to_gene(iso)) head(g)iso <- example_isoformic() g <- summarize_to_gene(assay(iso, "abundance"), tx_to_gene(iso)) head(g)
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.
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, ... )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, ... )
self |
|
group |
Column of |
levels |
Levels of |
contrasts |
The comparisons to test: |
method |
|
assay |
Counts assay to test. |
scale |
Logical, divide the counts by the overdispersion of the
replicates. |
min_count, min_prop
|
Filters described above. |
workers |
Number of workers for |
gene_name |
Gene names or IDs to keep in the result. The filter is applied after the test. |
... |
Unused. |
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.
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.
test_productive_fraction(), test_apa(), de_confidence()
iso <- example_isoformic() if (requireNamespace("edgeR", quietly = TRUE)) { res <- test_usage(iso, group = "condition", method = "diffsplice") head(res) table(res$contrast) }iso <- example_isoformic() if (requireNamespace("edgeR", quietly = TRUE)) { res <- test_usage(iso, group = "condition", method = "diffsplice") head(res) table(res$contrast) }
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.
transcript_features( self, gene_name = NULL, nmd_rule = 50, end_window = 50, ... ) splicing_events(self, gene_name = NULL, ...)transcript_features( self, gene_name = NULL, nmd_rule = 50, end_window = 50, ... ) splicing_events(self, gene_name = NULL, ...)
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. |
A tibble with one row per transcript.
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")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")
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):
"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.
"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.
"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).
"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.
"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.
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, ... )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, ... )
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 |
long_utr3 |
3' UTR length (nt) above which |
... |
Passed on to methods. |
coding_cutoff |
Coding probability above which a transcript is called coding (default 0.364). |
A tibble with one row per transcript.
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.
transcript_productivity(), transcript_features()
iso <- example_isoformic() orfs <- transcript_orfs(iso, gene_name = "RBPJ") orfs[, c("transcript_name", "orf_source", "orf_length", "nmd_class", "coding_probability")]iso <- example_isoformic() orfs <- transcript_orfs(iso, gene_name = "RBPJ") orfs[, c("transcript_name", "orf_source", "orf_length", "nmd_class", "coding_probability")]
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()).
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)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)
x |
An annotation directory path or an IsoformicExperiment. |
genome_fasta |
Path to a genome FASTA file ( |
transcript_fasta |
Path to a transcript FASTA file, see
|
overwrite |
Logical, replace existing sequences (default |
chunk_bytes |
Number of bytes read per chunk while streaming (default 64 MB). |
transcript_id |
Optional transcript identifiers to read; |
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.
The path of the written Parquet file, invisibly. The table has
columns transcript_id, sequence and seq_length.
transcript_orfs(), coding_potential()
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)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)
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.
read_treeterminus( path, salmon_dir = NULL, transcripts = NULL, ignore_after_bar = TRUE ) cut_transcript_trees( trees, x, cutoff = NULL, unresolved = c("transcript", "root") )read_treeterminus( path, salmon_dir = NULL, transcripts = NULL, ignore_after_bar = TRUE ) cut_transcript_trees( trees, x, cutoff = NULL, unresolved = c("transcript", "root") )
path |
A Newick file of TreeTerminus, or a folder holding
|
salmon_dir |
A Salmon output directory quantified against the same
index, whose |
transcripts |
Alternatively, the transcript names in |
ignore_after_bar |
Logical. Keep only the part of transcript names
before the first |
trees |
The result of |
x |
An IsoformicExperiment with inferential replicates (see
|
cutoff |
Inferential relative variance below which a node is well
determined (the |
unresolved |
|
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.
Singh NP, Love MI, Patro R (2023). TreeTerminus: creating transcript trees using inferential replicate counts. iScience 26(6):106961.
read_terminus_groups(), add_uncertainty()
nwk <- tempfile(fileext = ".txt") writeLines(c("((0,1),2);", "(3,4);"), nwk) read_treeterminus(nwk, transcripts = c("tA1", "tA2", "tA3", "tB1", "tB2"))nwk <- tempfile(fileext = ".txt") writeLines(c("((0,1),2);", "(3,4);"), nwk) read_treeterminus(nwk, transcripts = c("tA1", "tA2", "tA3", "tB1", "tB2"))
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.
tx_type_palette()tx_type_palette()
A named character vector of hexadecimal colours.
head(tx_type_palette())head(tx_type_palette())
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.
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, ...)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, ...)
self |
|
paths |
Salmon output directories (see |
group |
Name of a |
levels |
The two group levels to contrast, reference first. Samples
of other groups are left out of the contrast. |
n_draws |
Number of replicates to read; |
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. |
cor_cutoff |
Mean replicate correlation at or below which two isoforms
of a gene are called ambiguous: a number, or |
min_agreement |
Share of replicates that must agree on the direction
of a fold-change for it to be called stable. |
equivalence |
Logical, read the equivalence classes when present, or
the table returned by |
identifiability |
Logical, also compute which transcripts the
equivalence classes can tell apart ( |
run_qc |
Logical, add the Salmon run metadata (see
|
keep_draws |
Logical, keep the replicates in the object (needed to
recompute the tables and for |
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 |
... |
Unused. |
gene_name |
Optional gene names or IDs to keep. |
ambiguous_only |
Logical, |
pseudocount |
Pseudocount of the log2 fold-change (5, as in |
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.
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.
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.
read_inferential_replicates(), plot_de_confidence(),
isoform_switches()
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)$transcriptsquant_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_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.
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, ...)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, ...)
self |
An IsoformicExperiment with uncertainty tables (see
|
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. |
A ggplot object, or a named character vector for
confidence_palette().
add_uncertainty(), de_confidence()