Guided project
Module 3 · Figures that tell the truth · Self-checked
A colleague's draft figure has every common problem. Rebuild it properly from the course files, in R. Work through the six tasks, check each against its checkpoint, and tick it off. Nothing is submitted.
The draft
Panel 1: 3D bars of mean tooth length for the six groups, rainbow colours, y-axis starting at 5, ± SE bars, no units. Panel 2: a volcano plot in red and green, with all 159 significant genes labelled. Panel 3: a heatmap of raw expression values in the rainbow palette. Saved as a 72 dpi JPEG screenshot.
Read the draft slowly, one sentence at a time. Almost every phrase describes a choice that one of the Module 3 lessons warned against. Nothing here is a coding error: the draft would run without a single warning. That is what makes such figures common, and why checking them is a skill of its own.
How to approach this
You will rebuild the figure from the course files, not repair the draft. Work in one R script, in the order the tasks give, and keep it tidy enough that a colleague could rerun it.
This project brings the whole module together, from Choosing the right chart to Publication-ready export.
Rebuilding rather than repairing is deliberate. Each problem in the draft goes back to a decision made early, such as the chart type or the colour scale, and later touch-ups rarely undo it: removing the 3D effect from a bar chart still leaves a bar chart of means that hides the animals. Starting from the data lets every panel be designed for its question from the first line of code.
- Set up once, at the top. Load ggplot2, dplyr, patchwork, pheatmap and ggrepel; read toothgrowth.csv, de_results_example.csv and expression_example.csv; and define the
okabecolours, exactly as in Choosing the right chart. - One object per panel. Store each finished panel in its own variable, such as
pa,pbandpc, and look at it on its own before combining anything. A panel that is wrong alone will not be right inside a figure. - Check as you go. Compare each panel with its checkpoint before moving on. The checkpoints give numbers, such as 76 and 83, that your output should match exactly.
- Rerun from a clean start. When you finish, restart R and run the whole script from the top. If it rebuilds the figure without help, it is reproducible.
The lessons named under each task title are the ones to reopen. Their code is the starting point; you mostly combine pieces you have already run.
Expect panel A to take longest, because it combines a summary table with the raw points, and panel C to need the most care at assembly, because pheatmap draws outside ggplot2. If a step stalls, solve it on its own in a few lines, then return to the script. A typical pitfall is fixing one panel's appearance with settings the others lack, such as a different text size. Set the theme once, for example th <- theme_classic(base_size = 9), add it to every ggplot panel with + th, and the panels stay consistent.
List the problems
Choosing the right chart to Honest axes and scales
- Write down every problem in the draft, and the lesson that fixes it.
Hint. Go through the draft with the lessons as a checklist. For each panel, ask: is this the right kind of chart for the data (Choosing the right chart)? Does it show the individual values (Choosing the right chart and Showing distributions)? What do the error bars mean (Comparisons and uncertainty)? Do the colours carry the right kind of information, and can everyone see them (Colour that works for everyone)? Are the axes honest (Honest axes and scales)? Then look at labels, units and the saved file, which Multi-panel figures, Omics figures and Publication-ready export cover. Count what is missing as well as what is wrong.
Checkpoint: at least eight problems, including 3D, rainbow, truncated axis, SE bars without points, red–green, over-labelling, unscaled heatmap and the file format.
Panel A: the experiment
Choosing the right chart, Showing distributions and Comparisons and uncertainty
- Tooth length by dose and source, every animal shown, with means and 95% confidence intervals, in Okabe–Ito colours.
Hint. Start from the strip plot in Choosing the right chart, which already dodges the two sources apart within each dose. For the intervals, compute a summary table like the one in Comparisons and uncertainty, but grouped by both source and dose, so you get six rows with a mean and a CI half-width each. Draw that summary as a separate layer with its own data = argument. The summary layer must be dodged by the same width as the points, or the intervals will sit between the groups instead of on them.
Checkpoint: six groups of 10 points; at 2 mg the two sources overlap almost completely.
Panel B: the volcano
Colour that works for everyone and Omics figures
- Volcano plot of de_results_example.csv in blue and orange, with threshold lines, labelling only the five genes with the smallest adjusted p-values.
Hint. The volcano code in Omics figures does most of the work, including the status labels and colours. For the labels, sort the results by padj with order(), keep the first five rows in a small separate data frame, and pass only that data frame to the labelling layer. The ggrepel package, named in the key point of Omics figures, moves labels apart and draws a short line to each point when space is tight.
Checkpoint: 76 up and 83 down; five labels that do not overlap.
Panel C: the heatmap
Colour that works for everyone and Omics figures
- Clustered heatmap of expression_example.csv, z-scored by gene, diverging palette centred on zero, with a group colour bar.
Hint. Colour that works for everyone shows how to z-score each gene and build a blue–white–red palette with symmetric breaks; Omics figures adds the group annotation and leaves clustering switched on. Check the range of your z-scores before you choose the limits, so that white sits at zero and almost no values fall outside the scale.
Checkpoint: samples split into control and treated; two blocks of six genes change in opposite directions.
Assemble and export
Multi-panel figures and Publication-ready export
- Combine the panels with letters A–C at 180 mm wide; save as PDF and as PNG at 600 dpi.
Hint. Multi-panel figures joins panels with patchwork and tags them with plot_annotation(); Publication-ready export saves the result. Decide on a layout first: three panels in one row of 180 mm leaves each about 60 mm, so two on top and one below may read better. One thing to watch: pheatmap does not return a ggplot object, so patchwork cannot add it with + as it stands. Either wrap the heatmap's drawing with patchwork's wrap_elements() (the drawing is stored in the gtable part of pheatmap's result), or draw panel C with ggplot2's geom_tile() instead. Work out the expected pixel width before you open the PNG, as in the worked example in Publication-ready export.
Checkpoint: the PNG is about 4,250 pixels wide, and all text is still readable when the figure is printed at 180 mm.
Legend and alt text
Publication-ready export
- Write the figure legend and two sentences of alt text.
- Check the figure in greyscale.
Hint. Use the legend template in Publication-ready export: one sentence per panel, starting with the panel letter, saying what was measured, in how many, and what each point, line, bar and colour means. For panel B, give the thresholds you used; for panel C, say that values are z-scores. The alt text should state the findings, not describe the colours. For the greyscale check, view the PNG in any image viewer that can show it in greyscale, or print it in black and white.
Checkpoint: the legend explains every point, line, colour and error bar; the figure still reads in greyscale.
Go deeper: values outside the colour limits
In Colour that works for everyone the z-scores ran from −2.01 to 2.00, just past limits of −2 and 2. How software treats such values differs. If you draw panel C with ggplot2, using geom_tile() with scale_fill_gradient2(low = "#2166AC", mid = "white", high = "#B2182B", midpoint = 0, limits = c(-2, 2)), any value outside the limits becomes NA and is painted in the scale's grey missing-value colour, which a reader could mistake for missing data.
Adding oob = scales::squish to the scale draws out-of-range values in the end colour instead, dark blue or dark red. Either choose limits wide enough to hold every value, as the hint for task 4 suggests, or squish them and say so in the legend, for example "values beyond ±2 are shown at the end colour". Never let a silent grey cell hide your most extreme gene.
What you have practised
This project used every lesson of the module once: choosing a chart type, showing the data, honest error bars, safe colour, honest axes, multi-panel layout, omics plots and export. The same checklist applies to any figure you make or review, including figures in papers you read. When a figure looks surprisingly convincing, it is worth checking the axis start, the error-bar type and the colour scale before you believe it.
Looking back over the tasks, most of the fixes were not about R at all. Replacing bars with points, naming the error bars, z-scoring the heatmap and labelling five genes instead of 159 are decisions about what the reader needs; the code for each was a few lines you had already run. That is the habit this module aims to leave you with: decide what each panel must show, then make the code serve that decision.
The same questions work when you review someone else's figure. Can I see the individual values, or only a summary? What do the error bars show, and how many observations lie behind them? Where does each axis start, and is any scale logarithmic? Could a reader with red–green colour blindness tell the groups apart? Does the legend define every symbol? A figure that answers all five clearly is usually one you can trust.
Module 4, RNA-seq analysis, puts these skills to work on a real experiment: the airway data, in which airway smooth muscle cells from four donors were either treated with the steroid dexamethasone or left untreated. In RNA-seq counts and exploration you load the count table and check the samples with a PCA plot; Differential expression with DESeq2 tests every gene; and Volcano plot and interpretation draws a volcano plot and a heatmap of the top genes from those results. The volcano plot there uses the same thresholds, dashed threshold lines and ggrepel labels as panel B, and the heatmap centres each gene on its own mean, a close relative of the z-scores in panel C. Bring this module's checklist with you: those are the figures where honest axes, readable colour and sparing labels matter most.
Take it further
Apply the checklist to a figure from your own work. Then make the figures behind the data in Module 4: RNA-seq analysis.
A good first target is a figure you made before this module. Rebuild it from a script, then compare the two versions side by side: the differences are a record of what you have learned.
Further reading · Module 3Weissgerber et al. 2015: why bar charts hide the data, with examples. · All reading for this course
Up next
Lesson 1
RNA-seq counts and exploration