--- title: "PlotTrellis" output: BiocStyle::html_document: toc: false vignette: > %\VignetteIndexEntry{PlotTrellis} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r opts, include=FALSE} knitr::opts_chunk$set(message = FALSE, warning = FALSE) ``` 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): ```{r install, eval=FALSE} 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. ```{r app-example, eval=FALSE} 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: ```{r compose-screenshot-1, echo=FALSE, out.width="100%"} knitr::include_graphics("figures/sample_and_gene_selection.png") ``` 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. ```{r compose-screenshot-2, echo=FALSE, out.width="100%"} knitr::include_graphics("figures/track_composer.png") ``` To use PlotTrellis from R code instead, see [Your first figure in code](#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`: ```{r own-data, eval=FALSE} 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. ```{r wizard-screenshot, echo=FALSE, out.width="100%"} knitr::include_graphics("figures/wizard_manual.png") ``` 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](https://www.gencodegenes.org) (human and mouse: the "Comprehensive gene annotation" GTF) or [Ensembl](https://www.ensembl.org/info/data/ftp/) (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: ```{r code-example, eval=FALSE} 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 ``` ```{r code-example-run, echo=FALSE, fig.alt="Elf5 in mouse mammary basal cells and luminal progenitors: ATAC coverage and transcript counts for each, then the annotated transcripts and the gene."} library(PlotTrellis) proj <- pt_project(project_dir = file.path(tempdir(), "PlotTrellis-example"), samples_txt = pt_example()) pt_figure(proj, "Elf5", tracks = c("atac@Basal", "atac@LP", "transcript_counts@Basal", "transcript_counts@LP", "transcripts_annotated", "genes")) ``` # 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. # More in code - **Tracks** are listed top to bottom. `pt_tracks(proj)` lists every one the project has. `genes`, `transcripts_annotated` and the other annotation tracks need no sample; the rest name theirs after `@`. - **Comparisons** name two samples, the second being the reference: `"junctions_diff@KO vs Control"`. - **`parallel = TRUE`** repeats every track written without `@` for each sample, so `pt_figure(proj, "Elf5", c("atac", "transcript_counts", "transcripts_annotated", "genes"), parallel = TRUE)` is the figure above. `parallel = c("LP", "Basal")` picks the samples and their order. - **`region = "chr2:103,400,000-103,460,000"`** instead of a gene shows any coordinates. - **`pt_script(fig, "Elf5.R")`** writes a standalone script that redraws the figure, for edits the API doesn't offer. - **`run_plottrellis(proj)`** opens the same project in the app, and `pt_preload(proj, fig)` makes it open on `fig`, ready for someone who doesn't code. Everything a project keeps (settings, a copy of its samples table, caches) is in its `project_dir`; your data files stay where they are. # 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: ```{r sharing, eval=FALSE} 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 ```