Publication-template

This project is maintained by AndrewGYork

Technical note

A template for writing scientific papers

Andrew G. York1*

1Calico Life Sciences LLC, South San Francisco, CA 94080, USA

*Permanent email: andrew.g.york+template@gmail.com

A template for formatting scientific papers using HTML, CSS, and Javascript.

doi: 10.5281/zenodo.231328

Note that this is a limited PDF or print version; animated and interactive figures are disabled. For the full version of this article, please visit https://andrewgyork.github.io/publication_template

Examples

Scientific papers from my lab which use this template:

Introduction

Version control tools like Git, Github, and Github Pages are great for developing, sharing, and documenting code. Why not for science, too? Consider the following workflow:

I've been careful about dependencies; Git and Github are helpful, but not required. You can download a .zip of this repository, edit index.html with a text editor, and view the results with a web browser. I avoid Javascript which loads via the web, so you can work offline. My figure generation code depends on the Scipy stack, but this is easy to swap out; all you have to do is generate static images, put them in the proper folder, and link to them from index.html. You can generate your static images using any tool you choose. If you happen to use code to generate your figures, though, great! You can put this code in the figure_generation directory, enabling version control and simple reproduction of your results by others.

Writing directly in HTML/CSS/Javascript isn't for everyone. It's fiddly, has a learning curve, and requires obsessive attention to detail. In my experience, writing a scientific publication already fits this description, so it's a small price to pay, and one I'm already paying.

Math typesetting

I use MathJax for typesetting. I want to be able to work offline, but a local MathJax copy is huge, so I followed the recipe described by Tibor Simon to make a minimal version. The recipe's pretty cool; you delete most of MathJax, try to load it, watch your browser console, and copy files back one at a time until your browser stops complaining. I only support LaTex input; if you want more, you can follow Tibor's recipe and replace the contents of /javascript/Minimal-MathJax/.

Examples of paragraph equations:

$$\begin{equation}\prod_{\substack{1\le i \le n\\ 1\le j \le m}}M_{i,j} \end{equation}$$ $$\begin{equation}L' = {L}{\sqrt{1-\frac{v^2}{c^2}}}\end{equation} $$ $$\begin{align} B'&=-\nabla \times E,\\E'&=\nabla \times B - 4\pi j,\end{align} $$ $$\begin{equation}x = a_0 + \frac{1}{a_1 + \frac{1}{a_2 + \frac{1}{a_3 + a_4}}}\end{equation} $$
Example of inline math: \(\frac{a^3}{b}\)

Code syntax highlighting

Prism.js makes HTML syntax highlighting easy. I only included Python highlighting; if you want more, download a freshly customized version from prismjs.com and replace /javascript/python-highlighting/prims.js.

Example Python syntax highlighting:

import antigravity
antigravity.fly()
print("Whee!")

Automatic reference list

An example of how to include a citation: [Eswaramoorthy2014]. If you inspect the HTML, you'll see that inserting the citation is super clumsy, but at least you don't have to keep track of uniqueness, ordering, etc.

Static and interactive figures

Version control isn't a great way to organize images, but you can get away with it if there aren't too many, and they don't change too often. Figure 1 uses an image stored in the local repository.

Figure 1
Figure 1: A static figure using a local image. This image was generated by /figure_generation/figure_1.py.

Figure 2 is interactive; the images are pre-computed (by Python code, in this case) and stored in the local repository. Simple javascript changes the figure's img.src when the figure's select changes. The images are small and don't change much, so it's not horrible to store them in this repository. A similar figure with substantially more images would stretch the limits of this approach.

Figure 2
Period: (change this to adjust the period of the sinusoidal plot)
Figure 2: An interactive figure using local images. This figure's images were pre-generated by /figure_generation/figure_2.py, and switched dynamically by /javascript/update_figures.js.

Interactive figures can potentially contain huge numbers of images, which are clumsy to store in a version-controlled repository. My current preferred solution is to store such images in an auxiliary location. During the writing process, we generate these images automatically using the figure generation code and store them locally. Once the paper is ready to publish, we host a copy of these images in a second auxiliary repository. The figure update Javascript finds the appropriate image source for us.

Figure 3
Period: (change this to adjust the period of the sinusoidal plot)
Figure 3: An interactive figure using images that aren't stored in this repository. This figure's images were pre-generated by /figure_generation/figure_3.py, and switched dynamically by /javascript/update_figures.js.