Rendeiro group

Lab manual

Manuscript writing

This document provides practical guidelines for writing a manuscript. For insights on planning a project please see the project planning guide instead.

Manuscript writing should really be called "manuscript crafting" as it involves a lot more than text writing and formatting or figure making as it takes a lot of time, effort and skill to craft a good manuscript.

Figures

A crucial part of crafting a great manuscript is good communication of ideas through visual elements (figures), and their alignment with the text.

Here are André's tips for figure making based on practice. This has changed a little over time, but mostly coalesced on a fairly simple system.

Making plots (Python, matplotlib, seaborn)

  • Try to separate data processing from visualization (not just the early 'pipeline'-like processing, but also the statistical analysis).
  • Each script produces a set of plots into a results directory, with subdirectories matching the script or analysis name (more hierarchical if needed, e.g. different datasets).
  • Each plot file name should be self explanatory and contain enough information to track down its origin.
  • Except for obvious groupings or interrelations, avoid making figures with many subplots.
  • Create figures in matplotlib/seaborn always explicitly: fig, ax = plt.subplots(figsize=(3, 3))
  • For the most part aim for each subplot to have a square shape with about 3 by 3 inches. If creating a figure with multiple subplots, scale the figure size accordingly: fig, axes = plt.subplots(4, 2, figsize=(2 * 3, 4 * 3))
  • Always label the axes, and make use of a single statement to set many properties at once: ax.set(xlabel="Time", ylabel="Expression (log)", yscale="log")
  • For plot elements with many objects (e.g. scatter), rasterize only that element in order to reduce the size of the figure: ax.scatter(..., rasterized=True) or sns.clustermap(..., rasterized=True). Do not rasterize the whole axes, as that will make e.g. text elements uneditable.
  • Choose consistent colors across a project. Consider thinking of all factors being highlighted in the paper before starting the project. See colormaps here: https://matplotlib.org/stable/gallery/color/colormap_reference.html
  • Choose continuous colormaps for continuous variables (magma, viridis). Use divergent colormaps (coolwarm, RdBur, PuOrr) only when a central value has meaning (e.g. a Z-score).

Recommended settings for matplotlib

Inkscape: Export to SVG

import matplotlib.pyplot as plt

plt.rcParams['savefig.bbox'] = 'tight'  # To ensure that legends and elements outside the axes are included
plt.rcParams['savefig.dpi'] = 300  # To make sure any rasterized elements have good quality
plt.rcParams['savefig.transparent'] = True  # To remove the white background
plt.rcParams['svg.fonttype'] = 'none'  # To allow font to be editable in Inkscape
plt.rcParams['font.family'] = 'Arial'  # Use Arial as the font

Adobe Illustrator: Export to PDF

This is similar to the above, except for the font settings:

import matplotlib.pyplot as plt

plt.rcParams['savefig.bbox'] = 'tight'
plt.rcParams['savefig.dpi'] = 300
plt.rcParams['savefig.transparent'] = True
plt.rcParams['pdf.fonttype'] = 42
plt.rcParams['ps.fonttype'] = 42
plt.rcParams['font.family'] = 'Arial'

Assemble plots manually into a figure

Inkscape

  • Check the journal requirements and limitations for figures and their dimensions. Use A4 by default, not letter.
  • Here is a template figure: https://gist.github.com/afrendeiro/2d9975793629774ad73ea9d18bd7abf3
  • Add a plot to the canvas, resize it to an approximate desired size, remove all groupings, remove redundant objects, possibly despine plot (i.e. remove top right, top axes). Make whole plot into a group (or layer).
  • Be wary of resize operations that change aspect ratio. Be sure not to create artifacts. Here's some help: https://github.com/burghoff/Scientific-Inkscape (hasn't worked recently for me).
  • Use a consistent font family (Arial) for all text elements and only one or two font sizes (12 and 10). You can use the Find/Replace tool with Object types = 'text' to do this.
  • Add a lowercase letter label to each panel (font 16).
  • Add a label to the top of the Figure (i.e. Figure 1)
  • Name the figure files consistently Figure1.svg, SupplementaryFigure1.svg

Post assembly, automatic assembly and conversion of file types (bash, inkscape, minify, pdfunite):

Only in very rare cases it is worth it to have a full final figure generated as a whole.

Adobe Illustrator

Open PDF in Adobe Illustrator

  • Select everything:
    • Mac: ⌘ Command + A
    • Windows: Ctrl + A
  • Go to Object -> Clipping Mask -> Release, press until it can't be pressed anymore:
    • Mac: ⌥ Option + ⌘ Command + 7
    • Windows: Alt + Ctrl + 7

Congratulations! Now you have a clean plot ready for editing.

[!CAUTION] Removing clipping masks may affect elements, such as bars that extend offscreen.

Text

Manuscript text is usually written in Microsoft Word (docx) or LibreOffice Writer (odt). LaTeX is also supported; talk with André about starting with a LaTeX template.

Formatting

Use styles to format your text. Do not use whitespace (e.g. newlines and spaces) in the text to format the document.

  • Page:
    • Page size: A4
    • Page margins: 2 cm on all sides
  • Styles:
    • Default text style:
      • Font: Arial
      • Font size: 11
      • Line spacing: 1.15 lines
      • Paragraph spacing: 0.2cm below paragraph, 0.0cm above paragraph
      • Alignment: Justified
      • Color: Black
    • Headings (all inherit the above default style):
      • Title: Font size: 14, bold
      • Heading 1: Font size: 12, bold, paragraph spacing: 0.4cm above
      • Heading 2: Font size: 11, italic, paragraph spacing: 0.3cm above
      • Heading 3: possible but not recommended
    • Figure legends (inherit from default style except for settings below):
      • Legend below figure.
      • Font size: 10
      • Figure number and title: bold.

Structure

  • Title
  • Authors
  • Author affiliations
  • Abstract
  • Introduction
  • Results
  • Discussion
  • Methods
  • Data availability
  • Code availability
  • Acknowledgements
  • Conflicts of interest
  • References

File formats

Refer to research page for more details.

Edit this page on GitHub