PlotTrellis turns your sequencing data into multi-track genomic figures (transcript counts, transcript structures, splice junctions, coverage, comparisons between samples), in a point-and-click app or in a few lines of R.

Installation

PlotTrellis is not on CRAN, so repos tells R where to find it. BiocManager::repositories() adds the Bioconductor and CRAN packages that match your R (from scratch this can take up to 15 minutes):

install.packages("BiocManager")
install.packages("PlotTrellis", repos = c("https://aleks-wehi.r-universe.dev",
                                          BiocManager::repositories()))

Your first figure in the app

PlotTrellis ships one example: mouse mammary basal cells (Basal) and luminal progenitors (LP) around the Elf5, Ehf and Cat genes.

BiocManager::install("org.Mm.eg.db", update = FALSE)   # mouse gene annotation (for human data: "org.Hs.eg.db")
library(PlotTrellis)
run_plottrellis(project_dir = "PlotTrellis-example", samples_txt = pt_example())

A samples.txt is a text file listing a project’s samples and their data files, and pt_example() gives the path of the example’s. project_dir is the folder that holds everything PlotTrellis makes for this project. Here it is created in R’s working directory, but it can be any folder. Without it, the project is in ~/PlotTrellis.

The app opens with Elf5 and its tracks already picked: click Generate figure. Then try Ehf or Cat, or a different set of tracks.

To build your own figure on the Compose page, choose how many samples and which ones, then a gene or coordinates:

Drag tracks into the figure (drag again to reorder) and click Generate figure. The title, fonts, heights and colours are under Figure settings. The Output page downloads the figure as an SVG or as a standalone R script, and shows the gene’s transcripts and protein domains.

To use PlotTrellis from R code instead, see Your first figure in code below.

Your own data

The simplest way is to run the command above with a new project_dir and no samples_txt:

run_plottrellis(project_dir = "my-project")

A wizard guides you through listing your samples and their files, and saves them in the project folder as project_samples.txt. When you click Save (or Close), close that browser tab: the app reopens in a new tab from RStudio a few seconds later. To come back, run the same command. If a new project_dir already holds a project_samples.txt, the wizard offers to import it.

Apart from your data, the one file you need is your genome’s GTF: the annotation file that says where each gene and transcript is. Use the one your data was aligned or quantified with, if you have it. Otherwise download it from GENCODE (human and mouse: the “Comprehensive gene annotation” GTF) or Ensembl (other species), for the same genome build as your data. It can stay gzipped (.gtf.gz).

Your first figure in code

The rest of this vignette is for working in R. The example figure from the app:

library(PlotTrellis)
proj <- pt_project(project_dir = "PlotTrellis-example", samples_txt = pt_example())
fig  <- pt_figure(proj, "Elf5", tracks = c("atac@Basal", "atac@LP",
                                           "transcript_counts@Basal", "transcript_counts@LP",
                                           "transcripts_annotated", "genes"))
pt_save(fig, "Elf5.pdf")   # or .svg, .png

Elf5 in mouse mammary basal cells and luminal progenitors: ATAC coverage and transcript counts for each, then the annotated transcripts and the gene.

Your own data in code (writing a samples.txt)

A project can also come from a samples.txt, a tab-separated table with one row per sample under a few header lines. For example:

# data_root: /data/smithlab/tcell_2026
# gtf_path: /data/reference/gencode.v44.annotation.gtf.gz
# orgdb: org.Hs.eg.db
# genome_label: hg38
condition  colour   bw:atac                 paired-end:junctions        quantdir:salmon
Control    #1b9e77  atac/Control_merged.bw  junctions/Control_SJ.bed    salmon/Control
KO         #d95f02  atac/KO_merged.bw       junctions/KO_SJ.bed         salmon/KO

The lines starting with # are the project’s settings:

data_root: the folder your data files are in. The paths in the table are relative to it.
gtf_path: your genome’s GTF file (see above).
orgdb: your species’ annotation package, e.g. org.Mm.eg.db (mouse), org.Hs.eg.db (human).
genome_label: the genome build’s UCSC name, e.g. mm10, hg38.
Any other app setting, e.g. # fontsize: 12. A project’s project_samples.txt lists the ones changed from their defaults.

The columns (separated by tabs):

condition: the sample’s name.
colour (optional): the sample’s colour.
One column per kind of data file, headed type:name. The type says what the file is, and the name is what you call the track: bw:atac holds bigWig files and gives tracks called atac.

Type	File	Track
`bw`	bigWig	coverage (ATAC-seq, RNA-seq)
`quantdir`	a Salmon output folder (with `quant.sf`)	`transcript_counts`
`paired-end`	BEDPE or BED12	splice junctions
`hic`	`.hic`, `.cool`, `.mcool`	Hi-C contact map
`bed`	BED12	annotation

If you would rather not write it by hand, or already have a sample sheet with the same information, paste this section and your file list (or sheet) into an AI assistant and ask it for a samples.txt.

Then open it like the example: run_plottrellis(project_dir = "my-project", samples_txt = "path/to/samples.txt"). The project keeps its own copy, as project_samples.txt. Editing your samples.txt later updates the project the next time you run this command.

Sharing

To pass your data to someone else, send them the path to your samples.txt (for a wizard project, the project_samples.txt in its folder). They run the same command with a project_dir of their own:

run_plottrellis(project_dir = "tcell-project",
                samples_txt = "/data/smithlab/tcell_2026/samples.txt")

They need to be able to read your data files, so keep them on a shared drive and give data_root and gtf_path as full paths.

Their project is a copy: what they change stays in their project_dir. A later edit to your samples.txt reaches them when they rerun this command, unless they have changed their project since, and it replaces the settings they changed in the app.

To have the app open on a gene with its tracks already picked, as the example does, add two header lines:

# start_gene: Elf5
# start_tracks: atac@Basal, atac@LP, transcripts_annotated, genes