Before you start
- Have Trellis running: on a lab server, or on your own computer for practice (install).
- Load the demo. It adds two teaching labs, their accounts and example work in every module, and leaves your lab's own records alone. On the server, in the Trellis folder:
demo/demo.sh load
- Sign in as
demo, passwordtrellis-demo(or the one set withDEMO_PASSWORD).
To start the walkthrough again from a clean slate, run demo/demo.sh reset. The recordings are silent; each step is named in the green caption at the bottom.
Choose what to show
A genome, the tracks to lay over it, and where to start.
- On the Trellis home page, click Genome Browser.It opens on Choose what to show.
- 1 Genome: pick a reference.Everyone marks a genome shared with the whole suite — the Arabidopsis TAIR10 assembly here, 7 sequences and 119.7 Mb. Your lab marks one of your own lab's or chair group's.
- 2 Tracks: tick the data to lay over it.They are drawn in this order, top to bottom. The reference sequence and the ruler are always there. With many tracks, search above the list — type words from the name or the kind,
rnaseq rep2,bigwig,peaks— then Tick shown to tick everything found. - 3 Start at: click a chromosome, or type a region such as
Chr1:3,600-9,000. - Click Open in browser.Zoomed right out you see the whole chromosome; gene annotations are drawn within 2 Mb, so the track says zoom in to see features.
It remembers where you were and which tracks you had, for each genome, so next time it opens where you left off. Change genome or tracks takes you back to these choices.
A track belongs to the genome it was made for. Reads aligned to TAIR10 go on TAIR10, not on another assembly of the same plant. The browser checks, and offers the right genome when it can.
? Controls in the header opens a one-screen summary of everything below: moving around, selecting, and taking sequence away.
Move around, and how tracks look
Get to the gene, then make the tracks readable.
- Type a region into the box in the browser's own toolbar —
Chr2:9,544,000-9,550,000— and press Enter.Or pick a chromosome from the list beside it. Drag the tracks left or right to move along; the + and − buttons or the slider zoom; double-clicking empty space zooms in on that spot. - Click a feature once for its details: its name, type, position and the rest of its annotation.
- Click Bulk track settings, at the left of the bar above the browser. Tick the tracks to change, or Select all.
- Set their height, colour (a swatch, the picker, or a hex code like
#1f5fa8), how genes are drawn — expanded, squished or collapsed — and, for coverage, the scale.All ticked tracks change together, and the settings are kept with your view.
Find a gene by its name. Type AT3G01835, a symbol such as FLC or DRM2, or a full name such as flowering locus c into the same box. It is looked up in this genome's own annotation and BED tracks — genes first — so every Araport11 gene is found, and nothing you search for leaves the lab's server. A symbol is only found where the annotation gives one.
One track at a time: its gear (⚙) at the right does the same for that track alone.
Reorder or remove a track by dragging the grey handle at its right edge; remove it from its gear menu.
Expanded, squished, collapsed: expanded puts every transcript on its own row, which is how you see that AT2G22480 has two.
Select sequence
Four ways to say which stretch you mean.
- Double-click a feature.Selects exactly that gene, transcript or other feature: its full extent, on its own strand. On a feature, double-clicking selects rather than zooms.
- Shift and drag across the tracks for any stretch.A band follows the mouse and shows its length as you go.
- Select region: turn it on in the bar and a plain drag selects instead of moving along.Esc turns it off again.
- Type it: put a region in the box in the bar —
Chr2:9,545,283-9,548,640— and press Select.The browser goes there too.
What is selected shows as a green band down every track, and the bar above the browser turns green and reads Selected, with its position and length.
To let it go: Clear in the bar, Esc, or a click on the tracks outside the selected stretch.
A region drawn with igv's own ROI tool becomes the selection too.
Take the sequence away
Into the Sequence Editor, out to BLAST, or onto your computer.
- With something selected, four buttons appear in the green bar.
- Open in Sequence Editor — up to 30 kb.It opens as a new sequence in the Sequence Editor, in a new tab, with the annotations of the gene tracks on screen placed on it: exons, CDS, UTRs and so on. It is saved to your sequences there, named after the feature.
- BLAST at NCBI — up to 2 Mb.Opens NCBI's nucleotide BLAST in a new tab with the sequence filled in; choose the database there and run it. This sends the sequence to NCBI, outside the lab's server.
- Copy sequence — up to 2 Mb, to paste anywhere. Download FASTA — any length, even a whole chromosome.Anything too long for the others goes this way.
A feature on the minus strand is sent as it reads: reverse-complemented, with its annotations turned with it. A dragged or typed region is the plus strand.
Keep the header on sequence you take away. It names the feature, the assembly and the coordinates — >AT2G22480.1 TAIR10 Chr2:9545283-9548640 — which is what makes it findable again. A trailing (-) marks the minus strand.
Save a figure
Exactly what is on screen, kept in your notebook with the code to make it again.
- Get the view right first: the position, the tracks, their heights and colours, and any selection band.
- Click Save to notebook, at the left of the bar.A preview shows what will be saved.
- Give the page a title — it starts with the gene, the assembly and the position — and, if you like, a note saying what it shows.
- Click Save to Lab Notebook.A new page under today in your notebook, with the picture, a line saying which genome, position and tracks it shows, your note, and the figure as an SVG file. Open the page → takes you there.
Every figure gets a page under it: How to make it again. It lists the inputs, each a link that downloads the track under the name the code uses, the software to install, and the code with its files attached — an igv.js page and the view as session.json for a browser view, deepTools commands as run.sh for a profile, Circos's own configuration for a Circos plot. Someone outside the suite can make the same figure.
Download SVG saves it straight to your computer instead. SVG is a vector format: it stays sharp at any size, and its text and lines can be edited in Inkscape or Illustrator, which is what a journal figure needs.
A Circos plot
The whole genome round a circle, with every track you are showing as a ring.
- Show the tracks you want, in the order and colours you want, then click Circos plot.
- Give it a title, or leave the genome and what is drawn as the title.
- For each track, choose how its ring is drawn — histogram, line or heatmap — and how tall: thin, normal or tall.A heatmap is a band shaded from white to the track's colour: compact, so many tracks fit.
- Choose what to draw — the whole genome, chosen chromosomes, or a region — and the detail: coarse (about 300 steps), medium (800) or fine (2,000), or an exact step size.Small chromosomes (organelles and scaffolds, under 1% of the genome) can be left out. A region is filled in from your selection if you have one.
- Click Draw.A big genome at fine detail takes up to a minute. Your choices are kept for the next plot of this genome.
How it is drawn: the outer ring is the genome, each chromosome in proportion to its length with ticks in megabases. Inside it, one ring per track, the top track outermost, as one bar per step. For coverage that is the mean signal over the step; for a gene annotation, the number of genes starting in it — only features of type gene, so each gene counts once.
Options worth knowing: let coverage rings share one scale so their heights compare, put coverage on a log scale, highlight the selection you made in the browser, and label genes by name.
It saves like any other figure, and Download Circos files gives Circos's own configuration and data, so the plot can be redrawn outside the suite.
How it is done: binning, and Circos's own files
The plot is drawn by Circos itself (Martin Krzywinski's, the Debian package in the Genome Browser's image). The page sends the genome on screen, the tracks it shows with their colours and ring shapes, and your options; the server turns them into Circos's own files and runs it.
The step size. The stretch being drawn is divided into about 300 steps for coarse, 800 for medium or 2,000 for fine, and that size is then rounded to 1, 2 or 5 times a power of ten — so the whole Arabidopsis genome at medium lands on 200 kb, not 149,614 bp. The plot says which size it used, and an exact step in base pairs overrides the choice.
What goes in a bin. For a coverage track (BigWig) it is the mean signal over the step, read with pyBigWig; a step with no data gets no bar at all, rather than a zero. For a gene annotation (GFF) it is the number of features that *start* in the step, counting only those of type gene so each gene counts once and not again for its mRNAs and exons — a GFF with no genes falls back to all its features. For a BED track it is the features starting in the step.
The files. Download Circos files gives you exactly what the server ran:
karyotype.txt the chromosomes: the ideogram round the outside data/track-1.txt one line per step: chromosome, start, end, value data/links-1.txt a links (BEDPE) track, as arcs across the circle data/labels.txt the gene names you asked for data/highlight.txt your selection, shaded through the rings circos.conf the rings, colours, ticks and scales, outermost first circos -conf circos.conf # with Circos installed
Change a ring's colour or height, a scale, or a histogram into a heatmap, run that command, and you have the same plot outside the suite. The picture comes back from the server as SVG with the legend added on top, so it stays sharp and editable in Inkscape or Illustrator.
Limits worth knowing: a links track is capped at 25,000 arcs, a region must be at least 1 kb, Circos gets 150 seconds, and one plot is drawn at a time in each web worker. Only tracks you may view are drawn.
If a Circos plot goes into a paper, cite Circos: Krzywinski M, Schein J, Birol I et al. (2009) Circos: an information aesthetic for comparative genomics. Genome Research 19: 1639–1645.
Your own genomes and tracks
Put the lab's data on a reference, and say who may see it.
- On Choose what to show, click + Add tracks. Drop files on it, or choose them: one or as many as you like.GFF or BED for features, BigWig for coverage, or BAM, wig and bedGraph, which are converted to coverage on the server. A BigWig is ready at once; a large BAM takes a while. Each file's chromosome names are checked against the genome's, and ones another way round (
1,chr1,Chr1) are renamed to match. - Name the experiment the files belong to, and cite its paper or GEO accession.The track list groups tracks by experiment, and a colleague can then tell what they are.
- Click + Mark a sequence to find a guide, a primer or anything else on the genome.Give the sequences, one per line, with a name before each if you like; IUPAC codes are allowed. It looks on both strands and marks what it finds as a track of its own. It marks exact matches only, so a guide's near-matches are not shown.
- Click + Add a genome for a new assembly: a FASTA reference, up to 4 GB, with its assembly identifier.The identifier is what tracks name their chromosomes with, so take it from the assembly,
TAIR10. - Click Share genome to see and set who it reaches.A suite genome says Everyone in the suite sees this already; one of your own is shared with your lab, named labs or chair groups.
Look before you add a genome. If the assembly is already in the list, use it: shared genomes marked Everyone are there for the whole suite.
Name tracks so a colleague knows what they are: RNA-seq, root, 6 h ABA, rep 2, not sample3.
Methylation tracks are recognised by themselves. A BigWig of per-cytosine calls (values one base long, from 0 to 1 or 0 to 100) is marked methylation in the track list. Every analysis then measures it as a level, over the cytosines that have data, and drops the minus sign many GEO files give minus-strand cytosines. If it guessed wrong, change it under Its values in the track's Details. Keep CG, CHG and CHH in separate tracks.
Coverage tracks unlock Analyse: profiles and heatmaps, the difference between two tracks, a replicate check, a fingerprint, signal per feature, methylation against expression, and more (chapter 8). The demo genome has no coverage tracks, so Analyse says so until you add one.
Analyse: profiles, heatmaps, comparisons
What the tracks say across the whole genome, not just the stretch on screen.
- Click Analyse, beside Circos plot.What to draw has nine analyses. The coverage tracks you are showing are ticked to start with; only tracks you may see can be used, and at most 12 at a time. What it tells you, and how to read it opens that analysis's part of the Help page's Reading the analyses.
- Profile around features, and heatmap — the average signal of each track across a set of features.Choose the feature type from a gene annotation (the counts beside each type come from the track's own index: 33,318 genes, 321,301 exons), or the regions of a BED track. Up to four sets, each its own line. Scale each feature from start to end, or line them up on their start, end or middle — or on each peak's summit, from a narrowPeak BED — with 1 to 10 kb either side. Tick Heatmap to get every feature as a row as well, sorted by signal or grouped into 2 to 6 clusters. Each cluster's genes can be downloaded as a list, ready for a GO-enrichment tool, or kept as a BED track to view or analyse again. Only these limits it to a list of gene names.
- Difference between two tracks — A minus B, log2(A / B), A / B, A plus B, or their mean, in steps of 50 bp to 1 kb.The result is kept for your lab as a new coverage track, like an upload: it shows at once and can be drawn in Circos plots and profiles like any other.
- Replicate check: correlation and PCA — the chosen tracks compared along the whole genome in bins of 5 to 100 kb.A clustered correlation heatmap with the values written in (Pearson, or Spearman on ranks) and a principal component plot. Replicates should sit together and mutants apart; one that does not is worth a look before you trust it.
- Fingerprint — a quality check: whether a track's signal gathers in some places (enrichment) or spreads over the genome (background).Run a ChIP beside its input: a good ChIP bends well below the diagonal, an input stays near it. With the share of empty bins, the share of signal in the top 1% of bins, and the elbow point.
- Signal per feature — the mean of each track over every feature of one type, as a CSV with each feature's name and position.With exactly two tracks it adds their difference, and shows the fifty features that differ most straight away.
- Methylation against expression — each gene's methylation (over its body, or the 1 or 2 kb before it) against its expression from an RNA-seq track.Genes are grouped — no reads, then equal groups from lowest to highest expression — and drawn as box plots per group, every gene as a point with Spearman's ρ, and a profile of each group along the genes. With a table of every gene, and a ranked file per methylation track: methylated, silent genes first.
- Methylation and expression per gene, across samples — pair each sample's methylation track with its RNA-seq track (WT and mutants, tissues), and every gene gets its correlation across the samples, ranked, with p- and q-values.With few samples p-values cannot get small (2 / n!: 0.017 with five), and the caption says so: trust q, and use five or more samples.
- Tracks over the selection — a bar chart of each track's mean over the region you selected, in the tracks' colours. Synteny dot plot — a links (BEDPE) track with the genome along both sides, each link a short line drawn both ways round, so blocks that kept their order show as diagonals.
- Click Draw.Each result opens like a figure: save it to your Lab Notebook, download it as SVG, and download its data.
The demo genome has no coverage tracks, so every panel here says so and the Analyse tools stay greyed out. Add a BigWig, or a BAM for the server to convert, and they come to life — see chapter 7.
It runs in the background. All but the bar chart and the dot plot are jobs on the server: seconds for a replicate check, a few minutes for a profile of every gene with several tracks. My jobs, in the header, shows yours with progress bars, and opens a result when it is done. You can close the panel and keep browsing, up to three can wait at once, and results are kept for seven days.
Reading the analyses, on the Help page, says for each one what it tells you, when to reach for it, how to read what it draws and what can mislead — a link from every result goes straight to its part.
The last two need no job: the bar chart is just the tracks' means over your selection, and the dot plot is drawn by the page itself from the links track.
How it is done: deepTools, and the exact commands
The analyses are run by deepTools (Ramírez et al. 2016), installed in the Genome Browser's image. The web app checks you may see the genome and every track, then queues the work in an analysis_jobs table; the genome worker takes one job at a time, between genome conversions. Each command gets 30 minutes and ANALYSIS_THREADS processes (2 by default), and a job's files are kept for seven days.
Feature sets are not handed to deepTools as GFF. The chosen type is read out of the track's own feature index into a plain 6-column BED — chromosome, start, end, name, score, strand — sorted by position, with whitespace in names replaced by underscores and zero-length features dropped. That file comes back in the recipe, so the regions are exactly the ones used.
Profile and heatmap. scale-regions stretches every feature to the same length (3 kb by default, 500 bp to 20 kb); reference-point lines them up on their start (TSS) or end (TES) instead. Either way the flanks default to 2 kb (0 to 20 kb) and the bin to 100 bp (10 bp to 5 kb). --skipZeros drops the features with no signal at all.
computeMatrix scale-regions -S rnaseq-rep1.bw rnaseq-rep2.bw -R regions-1.bed \
--samplesLabel 'RNA-seq rep 1' 'RNA-seq rep 2' \
-b 2000 -a 2000 -bs 100 -m 3000 -p 2 --skipZeros -o matrix.gz --quiet
plotProfile -m matrix.gz -o profile.svg --perGroup \
--regionsLabel 'gene (33,318)' --startLabel start --endLabel end \
--plotTitle 'Mean signal' --yAxisLabel 'mean signal'
plotHeatmap -m matrix.gz -o heatmap.png --dpi 110 --colorMap viridis \
--heatmapHeight 18 --kmeans 3 --regionsLabel 'gene (33,318)'
The colour map is one of viridis, magma, RdBu_r, Blues or Reds, and --kmeans is only passed when you ask for clusters, with --outFileSortedRegions so each cluster's features come back as lists; without it the rows are sorted by signal. reference-point takes --referencePoint center for a feature's middle, and a summit is a one-base feature made from a narrowPeak file's tenth column.
Methylation tracks are measured as a level: without --missingDataAsZero, from a copy of the track without minus signs (bigwig_means.py unsigned). Steps with no cytosine are left out of the profile; for the heatmap only, they are filled from the measured steps beside them in the same row, so the picture is not all grey, while the profile and the matrix download stay as measured.
Difference between two tracks is bigwigCompare, which writes a new BigWig the server then registers as a track of your lab. For log2 and ratio the pseudocount is added to *both* tracks, so a zero cannot divide; it defaults to 1.
bigwigCompare -b1 mutant.bw -b2 wild-type.bw --operation log2 \
-bs 100 --pseudocount 1 -p 2 -o compare.bw
Replicate check bins every track the same way first, then correlates and reduces. The default bin is 10 kb (1 kb to 1 Mb). --removeOutliers drops bins whose signal is far above the rest, so one artefact cannot carry the correlation.
multiBigwigSummary bins -b rep1.bw rep2.bw mutant.bw \
--labels 'rep 1' 'rep 2' mutant -bs 10000 -p 2 \
-o summary.npz --outRawCounts bins.tab
plotCorrelation -in summary.npz -c pearson -p heatmap --plotNumbers \
--skipZeros --removeOutliers --colorMap RdYlBu_r \
-o correlation.svg --outFileCorMatrix correlation.tab
plotPCA -in summary.npz -o pca.svg --plotTitle 'Principal components'
Coverage is measured by the suite's own bigwig_means.py, not multiBigwigSummary: it counts bases without reads as zero, where deepTools averages over covered bases only and drops a bin with no reads, which took exactly the bins where replicates disagree out of the correlation. The fingerprint and methylation against expression figures are drawn by plots.py (deepTools' plotFingerprint reads BAM files only). Both scripts ship in each recipe.
Signal per feature is the same summary in BED-file mode. deepTools returns coordinates only, so the server matches each row back to the BED by chromosome, start and end to put the name and strand back, converts the start to 1-based, and writes signal-per-feature.csv. That last step ships in the recipe as name_features.py, so the table you get outside the suite is the same one.
multiBigwigSummary BED-file -b rnaseq.bw --BED regions.bed \
--labels 'RNA-seq' -p 2 -o genes.npz --outRawCounts raw.tab
python3 name_features.py # adds the features' names: signal-per-feature.csv
Every result carries a recipe.zip: a README.md naming the inputs and the deepTools version to install, run.sh with these commands as they were run (with each track under the name it downloads as), and the region BED files. That is what the How to make it again page in your notebook links to.
If a figure goes into a paper, cite deepTools: Ramírez F, Ryan DP, Grüning B et al. (2016) deepTools2: a next generation web server for deep-sequencing data analysis. Nucleic Acids Research 44: W160–W165.
Where next
- The Sequence Editor walkthrough picks up where chapter 4 leaves off: the sequence you sent across, ready to annotate, digest or design primers on.
- The bisulfite primers chapter shows the other direction — the editor asking the Genome Browser to check every primer against a genome with BLAST.
- The Genome Browser's own Help page (Help, top right) covers the Analyse tools and how to read each one, methylation tracks, chromosome names, and what to do when a track is refused.
- The HPC Terminal walkthrough: align the reads on the lab's cluster, then bring the BigWig back here.