Best Paper Award ceremony at the IEEE FNWF banquet. Photo by Thomas Sandholm.

This achievement is not ours alone. It reflects the support and collaboration of many - from our colleagues and mentors to the broader community of researchers and professionals who continually inspire us. Our sincere thanks go to the IEEE FNWF for considering our work and to everyone involved in the conference.

A special mention to my co-authors Filippo Vannella, David Sandberg, and Rickard Cöster. Your insights and hard work were crucial in this endeavor. Working with you has been a rewarding experience. Together, we also extend our gratitude to all who contributed in various capacities, not least the coffee roasters who kept us going!

Congratulations to the other awardees. It’s an honor to be recognized alongside such talented peers.

For those interested, our paper is available here (DOI: 10.1109/FNWF58287.2023.10520606). We welcome your thoughts and engagement. Lastly, a thank you to Thomas Sandholm for capturing the pinnacle of our journey in this photograph.

We look forward to continuing our research and sharing our findings with the community.

Our paper, mmWave Beam Selection in Analog Beamforming Using Personalized Federated Learning was awarded the Best Paper Award.

Introduction

I still remember the issues I had, many years ago, trying to build my Master thesis report using latex and dvips. Since then my build process has gone through a few iterations, to simplify, to make it faster, or to accommodate some new thing that I learned. Frustrated by the long build times, I have tried many things which may or may not have helped. The discussion (for example  Speeding up LaTeX compilation) seems to be plagued by hearsay. For a typesetting system that is used by scientists, the discussion is unexpectedly remarkably unscientific.

In this blog post we will go on an exploration of this rabbit hole, unraveling the intricacies of different LaTeX build systems. We will look at LaTeX compilation methods, comparing and contrasting different local build methods. By the end, you will likely choose another build system than you currently have.

Background

Why don’t just use Overleaf?

 Overleaf is fantastic, but a local LaTeX build environment can offer advantages over Overleaf in certain situations. A key benefit is control. With a local setup, users have complete control over their LaTeX distribution, packages, configuration and development environment. For me, the enhanced privacy and security is the most important reason to using a local build environment.

 Overleaf shines in collaborative and cloud-based settings when teams working on LaTeX documents can work simultaneously in the same document. It also eliminates the need to install and manage LaTeX distributions and packages, making it accessible to less experienced users.

Installing LaTeX

Your method of installing LaTeX varies with your operating system, the level of control you want, and other constraints. We will not go into this in detail here, see Getting LaTeX and Free TeX implementations. Once you have LaTeX installed, Bootstrapping your next LaTeX project and Top 10 LaTeX packages for academic writing are good next steps.

Building a LaTeX document

LaTeX employs a multi-pass typesetting process to enable various features like table of contents, lists of figures, cross-referencing, glossaries, indexing, and bibliographic citations. In this process, the data generated during one pass (compilation) is saved to intermediate files and then serves as input for any subsequent passes.

We have many choices to make here (see  What are the pros and cons pertaining to “latex -> dvipdfm” versus “latex -> dvips -> ps2pdf”? ), but in this case we know we want a Portable Document Format (PDF), .pdf, file. There are some differences depending on which workflow we pick here, but for this document we can pick any of them.

The multi-pass typesetting process involves several steps to create a PDF document with references using BibTeX and glossaries using makeglossaries:

1. Compilation with LaTeX. First we run pdflatex on the input .tex file. This initial compilation generates an intermediate .aux file containing information about citations, cross-references, and glossary entries. Since we are using the package glossaries-extra, we also get a makeindex style file .ist and an .acn file.

2. BibTeX for References If we have references in our document, we need to run BibTeX on the .aux file. BibTeX reads our bibliography database (.bib) and generates a .bbl file, which contains the formatted reference information.

3. Glossaries with makeglossaries If we have a glossary in our document, we use makeglossaries on the .aux file. makeglossaries reads the glossary definitions and generates the necessary files to include glossary entries in our document.

4. LaTeX Compilation (2nd Pass) Now we need to run pdflatex on the .tex file again. This time, LaTeX incorporates the formatted references from the .bbl file into our document. If there are any citations, they will be correctly numbered and formatted in the reference list, but the citations themselves will be rendered as [?].

5. LaTeX Compilation (3rd Pass) Running pdflatex on the .tex file once more ensures that glossary entries are properly integrated into your document and that citations are properly numbered.

6. Final compilations We need to repeat the pdflatex compilation step as many times as needed to resolve all cross-references and ensure the document is correctly formatted. LaTeX may issue warnings or errors during this process that need to be addressed. In our case, for this document, we only need to run pdflatex three times in total.

7. PDF Generation Once all the necessary information is integrated into your document, a PDF file is generated as the output.

See  File extensions related to LaTeX, etc and  latex-auxfiles for more information on different file formats that you might encounter during the build process.

Method

The document

The example document we will use in the remainder of this post is based on the  IEEE conference template (Shell, 2002). We will make some changes, for example adding a reference file using BiBTeX and a glossary using the glossaries-extra package. We will also add three example figures. These figures are available both in .eps and .pdf format, so that we don’t need to run an expensive conversion process for each figure. We will include these figures without the file suffix, for example

1
\includegraphics[width=.9\linewidth]{example-image-a}.

The first page contains our title and a figure.

The second page contains some references.

The third page contains the reference list and an acronym.

The last and fourth page contains the list of acronyms.

There are many things that effect the compilation times of a LaTeX document. See  What affects compilation times, especially in longer documents?. The document we use here is short and doesn’t contain a lot of features, and we do this to keep compilation times low since we will be repeating this build many times.

You can view the  source code for this document on Overleaf.

Timing measurements

To be able to compare the different methods, we will use a short timing script. For each subdirectory it will run make clean test.pdf, 25 times each and measure the time with /usr/bin/time. The different build methods fall into different categories, see the following sections for a quick introduction to each category.

Experiments

If you’d like to follow along at home, please take a look at this Gitlab repository.

Running bare commands

Here’s a short summary of how to build a LaTeX document using the pdflatex, bibtex, and makeglossaries commands in the terminal

pdflatex test
bibtex test
makeglossaries test
pdflatex test

This is the classical method, used by hopefully very few people and is included here for completeness.

arara

Arara (Island of TeX, 2023) is a build tool for TeX documents and other tasks. Arara simplifies the compilation process by allowing users to define compilation sequences through a user-friendly configuration in the source file itself. With its intuitive but explicit inline-comment-based syntax, Arara lets you specify various compilation steps, such as running pdflatex, bibtex, and makeglossaries, in a defined order.

% arara: pdflatex
% arara: bibtex
% arara: makeglossaries
% arara: pdflatex until !found('log', 'undefined references')

latexmk

latexmk is a command-line tool designed to simplify the process of compiling LaTeX documents. It automates the compilation workflow by intelligently handling multiple runs of LaTeX and associated tools to ensure that all references, citations, cross-references, glossaries, and bibliographies are resolved correctly. latexmk is included in TeX Live. To customize the behavior of latexmk we can use Perl-scripts, and here we give a short example of a document specific configuration file that also includes makeglossaries.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
add_cus_dep('glo', 'gls', 0, 'run_makeglossaries');
add_cus_dep('acn', 'acr', 0, 'run_makeglossaries');

sub run_makeglossaries {
  if ( $silent ) {
    system "makeglossaries -q '$_[0]'";
  }
  else {
    system "makeglossaries '$_[0]'";
  };
}

push @generated_exts, 'glo', 'gls', 'glg';
push @generated_exts, 'slo', 'slg', 'sls';
push @generated_exts, 'acn', 'acr', 'alg';
$clean_ext .= ' %R.ist %R.xdy';%

To compile a document we can run latexmk -pdflatex -bibtex -r latexmkrc main.tex.

See  How does Overleaf compile my project? for a longer discussion on latexmk and customization.

rubber and rubber-info

rubber is a command-line tool designed to simplify the process of compiling LaTeX documents. Like latexmk, it automates the compilation workflow, aiming to provide a seamless and efficient way to handle LaTeX projects with various dependencies. We run this with the command rubber -d -m glossaries test.tex.

❯ pipenv run rubber-info test.tex
There was no error.
There is no undefined reference.
There is no warning.
There is no bad box.

scons

SCons is a Python-based Open Source build system that simplifies the process of building and managing complex projects.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Make sure scons finds executables
import os
env = Environment(ENV=os.environ)

# Target and source files
pdf_output = env.PDF(target='test.pdf', source='test.tex')

# The Precious function is a method provided by SCons to mark a target
# as "precious" or "not to be deleted." This means that if SCons decides to
# delete temporary files or intermediate build artifacts after a build, it will
# not delete this particular target file even if it's considered an intermediate
# or temporary file.
# https://www.scons.org/doc/0.96.91/HTML/scons-user/c1924.html
env.Precious(pdf_output)

latexrun

latexrun is a Python-based LaTeX builder designed to fit into a larger build system. It hides the circular dependencies of compiling LaTeX documents and shows errors and warnings in a user-friendly format.

 See LaTeX run. Run latexrun.. Here we use a fork of  latexrun that also supports makeglossaries.

Using a precompiled preamble

The first part of your document, the preamble, changes must less often than the body of the document. We can use this to our advantage by pre-compiling the preamble. We need to split our file into a preamble, and a body part and annotate each part properly.

The preamble should end with \endofdump.

1
2
3
% static part
...
\endofdump

We can compile this part with LaTeX in the following way latex -ini -jobname="preamble" "&latex" mylatexformat.ltx "preamble.tex". This will result in a file called preamble.fmt which we can reference in the body of the document with

1
2
3
4
%&preamble
\endofdump
\begin{document}
...

See Faster LaTeX part IV: Use a precompiled preamble and Glossaries and mylatexformat incompatible?.

Ramdisk

Mounting a directory as a RAM disk can significantly speed up tasks like LaTeX compilation by using RAM for storage instead of the hard drive. Here we create a small RAM disk that just fits our document. How to mount the ramdisk in practice depends on your operating system and the details are therefore left to the interesting reader to figure out.

Flags

In LaTeX, flags like batchmode and draftmode can help you optimize the compilation process. Using batchmode suppresses most output, making the build faster and less cluttered in the terminal. This is useful when you’re confident your document is mostly error-free and want a quicker compile. The draftmode flag, on the other hand, speeds up compilation by skipping the inclusion of images and performing only minimal typesetting. This is great for quick previews where fine details aren’t necessary, such as early steps in the compilation process. Both flags can be added when running pdflatex or other LaTeX compilers, like pdflatex -interaction=batchmode test.tex or pdflatex -draftmode test.tex.

Dvips

In the early days of LaTeX, the standard workflow involved compiling the LaTeX source code into a Device Independent (.dvi) file. This format was platform-agnostic but not easily shareable or viewable. To produce a more accessible Portable Document Format (.pdf), users had two primary routes:

• Convert .dvi to PostScript (.ps) using dvips, and then convert the .ps file to .pdf using ps2pdf.
• Use dvipdfm to directly convert the .dvi file to .pdf.

These methods were often cumbersome but necessary prior to the advent of pdfLaTeX, which allowed for direct compilation to .pdf files. We will include these older pipelines in our list of experiments to provide a more comprehensive view of the evolution of LaTeX.

llmk

llmk (Takuto Asakura, 2025) is a lightweight LaTeX build tool that takes a minimalist approach: configuration lives either in a .llmk.toml file or as magic comments embedded directly in the .tex source, eliminating the need for a separate build script. It handles multiple compilation passes automatically, similar to latexmk, but with a simpler configuration surface. Build a document with llmk document.tex.

Results

Build-system benchmark summary (n=25 runs per system, time as mean ± 95% CI).

Build times

Our most important metric, and the one we set out to measure in the beginning, is the build time. Faster build times allows you to iterate more quickly through drafts. For those new to LaTeX, a slow build process can be discouraging, and comparing to other systems such as Typst, LaTeX is slooow. For me personally, long build times can interrupt my flow and concentration, impacting overall productivity.

Build times

The build system with the fastest build time is max_combo with an average build time of only 2.23 seconds – a combination of a precompiled preamble, latex via dvi, draftmode on the early passes and -interaction=batchmode. This speeds up the build a lot! In fact, in the top-3 of the list we see a lot of the same type of pipeline. However, max_combo is a little bit complex to setup, as we will take a look at in Ease of use. The fastest build is now 20% faster than the naive baseline and 40% faster than latexmk. Interestingly, one of the newest tools llmk is the slowest.

Manageable output

Human-understandable output, especially during errors, is crucial in LaTeX document building, since LaTeX is notoriously bad here. Most of the information printed isn’t very useful, so it would make sense to try and reduce this and keep the output to a minimum and restrict it to errors and warnings. In this test we simply count the number of lines on stdout, but it should be said that some of these build systems, such as latexrun have really nice colored output in the case things do go wrong.

Number of lines printed to stdout.

The first part of the list is dominated by build tools such as latexrun, arara and rubber that hide clutter and only show errors and warnings.

Ease of use

A build system must of course be easy to use, and as a proxy for that we measure the number of characters in the Makefile target + any sidecar configuration files (this is new since the 2023 post.) In the case that you do use a Makefile, simply running make would of course be easy enough.

Number of lines in the Maketarget

Personally, I don’t mind a little bit more complicated setup since I do it once and just copy for all new projects.

File size

A smaller file size offers advantages in terms of ease of handling, quicker uploads, and efficient storage. Therefore, the file size serves as a crucial parameter in evaluating performance.

PDF file size

It is interesting that there is such a big difference between the smallest and largest file size, even for such a simple document. For normal use this has little effect in 2026.

Final score

In the spirit of Eurovision and Melodifestivalen, we will adopt a point allocation system that mirrors the excitement and competition of these iconic music events. In Eurovision, each participating country awards points to their favorite songs, with the famous ‘douze points’ (12 points) reserved for the top choice. Similarly, the runner-up receives 10 points, acknowledging outstanding performances, and we will continue this tradition here.

Total scores received.

The build system with the greatest final score is latexrun_ramdisk_preamble – a combination of a precompiled preamble, a ramdisk, and latexrun.

We have seen how we can improve the compilation time for a small toy project, but these improvements carry over to real documents as well. For example, compiling a recent IEEE paper using latexrun took 16.87 seconds compared to 25.71 seconds using latexmk.

Related work

There are many general build systems such as Snakemake (Koster & Rahmann, 2012), GNU Make, CMake, etc that can be used also to build LaTeX documents. There are also many LaTeX specific build systems such as make-latex, AutoLaTeX and ltx2any, that didn’t make it into this comparison for one reason or another and I hope to return to them at a later date.

Each of these tools can be used in a more general pipeline as explored in How to annoy your co-authors: a Gitlab CI pipeline for LaTeX .

If you have many TikZ (Feuersänger et al., 2014; Tantau, 2007) or pgfplots (Feuersänger, 2014) figures, it might be worthwhile to externalize them (Wenneker, 2012). See also Create publication ready figures with Matplotlib and TikZ.

Discussion and limitations

In this blog post, we have tried to cover the most common build systems and tool combinations for LaTeX document compilation. These systems have been chosen based on their popularity and widespread use within the LaTeX community. However, we should recognize that the world of LaTeX is vast, and new tools and approaches are continually emerging. Let me know in the comments if your favorite build system is not covered!

Since the writing of this post (2023), Tectonic has matured as a XeTeX-based alternative. We exclude Tectonic here because it replaces the pdflatex engine making it incompatible with the IEEE pipeline.

Therefore, one obvious limitation of this blog post is its inevitable inability to encompass every possible LaTeX build system and tool combination. The LaTeX ecosystem is dynamic, with developers and enthusiasts constantly devising innovative ways to streamline the document creation process. As a result, there may be niche or specialized tools that we have not explored here.

Some characteristics of a build system might be more important to you than others. For example, the output from latexrun in the case of a fault is much easier to read than for other build systems, and it leaves a build directory that is almost clean. However, build directory cleanness is not measured in this blog post.

Your choice of a LaTeX build system should of course be guided by your individual preferences and workflow requirements. For example, when selecting a build system, consider factors such as your operating system and LaTeX distribution. Some tools are more compatible with specific platforms, and this compatibility restricts what options are available to you.

FAQ

Which build system should I use?

latexrun with a precompiled preamble is the best all-round choice: lowest stdout noise, clean error output, and near-top build speed with minimal configuration. If raw speed is the only priority and you don’t mind a more complex setup, max_combo wins on time.

Does this apply to large real-world documents?

Yes. Compiling a recent IEEE paper with latexrun took 16.87 s versus 25.71 s with latexmk — the relative gains hold as document size grows.

What about LuaLaTeX or XeLaTeX?

All measurements use pdflatex, which is required by many academic conferences and journals (including the IEEE template used here). Some findings may transfer to other engines, but we have not tested this.

Why is llmk the slowest?

llmk placed last in our benchmark at 5.62 s — roughly double latexrun. We haven’t identified the specific cause; it may warrant a separate investigation.

Conclusion

For LaTeX document compilation, choosing the right build system is an important, but often overlooked, decision. While each system we explored has its strengths, latexrun emerges as the champion, combining efficiency, reproducibility, and versatility in a single package.

Now, let’s use the regained seconds to improve what truly matters – your content.

AI Disclosure

The original benchmarks were run in 2023. The 2026 update — including the revised ease-of-use methodology, llmk results, and quality improvements to this post — was developed with AI assistance (Claude by Anthropic).

Introduction

Whether you’re a seasoned LaTeX user or just beginning to explore its capabilities, this compilation is aimed to make your academic papers seem just a little bit more polished than your competition. I am not promising that it will increase your chances of acceptance, that we will explore in another post.

In an earlier post we had a look at ten LaTeX packages, but in this post we will look at commands and macros. If you are starting a new project from scratch, Bootstrapping your next LaTeX project covers project structure and build automation. So, without further ado, and in no particular order, here are 10 18 useful LaTeX commands, macros and other tips for your writing pleasure.

Commands, macros and other tips

Math modes

When writing math in a paper, you can use the LaTeX syntax \( x = 1 \) (or \[ for inline math mode (Wright, 2022). This will sometimes provide better error messages, and having a begin and end point is nice if you ever would like to parse the document with a script. The TeX syntax $ x = 1 $ works as well, and some will say that this is more readable. Read about other subtle differences at  Are \ ( and \ ) preferable to dollar signs for math mode?

It is common that LaTeX introduces a line break inside the equation, which might not look great for inline math. You can use curly brackets to avoid the line breaking, for example \({ x = 1 }\).

Dynamic delimiters

Dynamic delimiters in LaTeX are great because they automatically adjust their size to match the content they enclose, increasing readability of mathematical expressions.

You can manually vary the size of delimiters such as parentheses with \big(, \Big(, \bigg( and \Bigg(.

However, almost always I use dynamically sized delimiters.

1
\left( \sqrt{a}+\sqrt{b}\right )^2

which produces

as opposed to

without using \left( and \right).

I recently learned we can do even better by declaring paired delimiters (Zeng, 2023)! By using the mathtools (Madsen et al., 2022) package we can define a paired braces with

1
\DeclarePairedDelimiter\braces{\lbrace}{\rbrace}

Then we can use the command \braces*{ ...} (note the starred version here) (Zeng, 2023).

Read more about brackets, parantheses and scaling the middle vertical line in  Brackets and Parentheses and  How to automatically scale \mid within delimiters. Read more about declaring paired delimiters at  Automatic left and right commands.

Numbers and units

siunitx (Wright, 2026) is a powerful tool for typesetting and formatting scientific and technical documents. It specializes in handling units, quantities, and numerical values, ensuring proper spacing, alignment, and consistent appearance.

1
2
3
4
5
6
7
8
9
10
\usepackage{siunitx}

% SI unit setup
\sisetup{
    exponent-product=\cdot
}

\DeclareSIUnit{\belmilliwatt}{Bm}
\DeclareSIUnit{\dBm}{\deci\belmilliwatt}
\DeclareSIUnit\px{px}

This allows us to add a number and unit with \qty{52}{\ampere\meter}. A number can be typeset with \num{1e5}. We can even typeset ranges with \qtyrange{1}{99}{\px} or \numrange{1}{99}. In an earlier post, we looked at using Pandas (pandas development team, 2020; Wes McKinney, 2010 ) to produce nice looking tables with no manual steps, and here we also used the table format S from siunitx.

Spaces and domains

Here are a few definitions of domains that I use.

1
2
3
4
5
\newcommand{\Z}{\mathbb{Z}} % Integer numbers
\newcommand{\R}{\mathbb{R}} % Real numbers
\newcommand{\N}{\mathbb{N}} % Natural numbers or prime numbers
\newcommand{\C}{\mathbb{C}} % Complex numbers
\newcommand{\Np}{\mathbb{N}^+} % Natural numbers including 0

For example \mathbb{N}^+ = \mathbb{N} \setminus \{0\} \(\mathbb{N}^+ = \mathbb{N} \setminus \{0\}\). To denote the empty set, I prefer $\varnothing \(\varnothing\) over \emptyset \(\emptyset\). For this, and many many more notations, see (Siek, n.d.).

Bachmann-Landau notations

Bachmann-Landau notation, a fundamental concept in theoretical computer science and mathematics, offers a concise and standardized way to describe the growth rates of functions and their relationships in mathematical analysis. Named after the mathematicians Paul Bachmann and Edmund Landau (Wikipedia contributors, 2023), this notation employs symbols like \(\mathcal{O}\), \(\Omega\), \(\Theta\), \(o\), \(\omega\) and \(\sim\) to articulate upper, lower, and tight bounds, on the behavior of functions as their inputs become sufficiently large.

Put this in your document preamble.

1
2
\usepackage{amssymb}
\newcommand{\BigO}[1]{\mathcal{O}\!\left(#1\right)}

Then we can use the command \BigO{} like this:

1
\BigO{n\log{}n}

This will produce \(\mathcal{O}\!\left(n \log{n}\right)\). Here is a Complete list of Bachmann-Landau notations. The \! adjusts the spacing to be more pleasing (Thanks u/Tensor_Product_9377!).

Defining new math operators

Operators such as \(\sin\) and \(\cos\) are typeset in a roman font in math mode (Higham, n.d.) . If you need to define a new operator, you can use amsmath to make sure spacing is consistent with the already defined operators.

1
2
3
4
5
6
7
8
9
10
11
\usepackage{amsmath}
\DeclareMathOperator{\tr}{tr}
\DeclareMathOperator*{\Max}{Max}
\DeclareMathOperator{\Prob}{\mathcal{P}}
\DeclareMathOperator{\sgn}{sgn}
\DeclareMathOperator{\DFT}{DFT}

\begin{displaymath}
  \Max_{x\in A} f(x) \qquad  \End_R V
\end{displaymath}
\def\diag{\mathop{\mathrm{diag}}}

See  newcommand vs. DeclareMathOperator and Defining a new log-like function in LaTeX for more information.

Typesetting a definition

Sometimes I see the notation := to denote a definition, and I don’t particularly care for it since it reminds me of the Walrus operator introduced in Python 3.8 (Hettinger, 2019). Even though the Walrus operator is an assignment operator, it looks as code, not mathematics. I much prefer the overset triangle \triangleq \(\triangleq\) from amssymb.

If you’d rather use an overset text def, here is how to do that.

1
\newcommand\myeq{\mathrel{\overset{\makebox[0pt]{\mbox{\normalfont\tiny\sffamily def}}}{=}}}

Overset text

amssymb

See  Triangle on top of propto that matches \triangleq,  Notation for definition and equivalence,  How do I put text over symbols? and  Delta-equal to symbol for more information on the topic.

Vectors and matrices

When I studied physics, my preferred way of writing vectors was using \vec{x} \(\vec{x}\). I used to prefer bold symbols for vectors and matrices using the bm package \bm{x} \(\bm{x}\).

See  bm package versus \boldsymbol for more information.

However, under unicode-math the recommended bold commands are \symbf (bold upright) and \symbfit (bold italic). \mathbf still works for backward compatibility and is aliased to \symbf — bold upright. The bm package is no longer needed and is incompatible with unicode-math’s symbol slots.

Transpose symbol

Here is a controversial topic on which transpose sign to use. I prefer \intercal over T any day of the week, but I agree with the user @Heiko Oberdiek that it is typeset a little too low for capital symbols (such as matrices). For lowercase symbols, just using \intercal looks better to me. See the full discussion on  What is the best symbol for vector/matrix transpose?.

1
2
3
4
\makeatletter
\newcommand*{\transpose}{{\mathpalette\@transpose{}}}
\newcommand*{\@transpose}[2]{\raisebox{\depth}{$\m@th#1\intercal$}}
\makeatother

Transpose example

I would like to have one macro for both lowercase and for uppercase symbols alike.

Overbrackets and underbrackets

Brackets, and braces, provide an excellent way of highlighting a part of an equation to be able to explain in better.

1
2
3
\begin{equation}
    \min_{\bm{w} \in \mathbb{R}^d} \mathcal{L}(w) \triangleq \min_{\bm{w} \in \mathbb{R}^d} \underbracket[.25pt][12pt]{\sum_{k=1}^K \frac{n_k}{n} \overbracket[.25pt][12pt]{\frac{1}{n_k} \sum_{i \in \mathcal{P}_k}  \underbracket[.25pt][10pt]{\ell(\bm{x}_i, y_i, \bm{w})}_{\text{sample}\,i\,\text{loss}}}^{\text{client average loss}}}_{\text{population average loss}}
\end{equation}

Under and over-brackets example

Inline TikZ

Sometimes it is easier to explain something with a small figure instead of creating some notation that is difficult to understand. I like to use this in a figure caption for example. We can use the tikz package (Feuersänger et al., 2014) for this.

1
2
3
4
5
6
7
8
9
10
\documentclass[varwidth=true, border=0pt, convert={outext=.png}]{standalone}
\usepackage{tikz}
\usepackage{xcolor}
\newcommand{\sharedkey}{
    \raisebox{-.5 ex}{\tikz{
    \draw[fill=blue, draw=white] (0ex,0) arc(90:270:1ex) -- cycle;
    \draw[fill=red, draw=white] (0ex,0) arc(90:-90:1ex) -- cycle; }}}
\begin{document}
\(x = \sharedkey\)
\end{document}

Inline TikZ example

See  Tikz picture inline for some other examples. For complete figure workflows in academic papers — including pgfplots and Matplotlib exports — see Create publication ready figures with Matplotlib and TikZ.

Figure up top

It is advantageous to put a nice overview figure in the top right corner (Huang, 2018), but it can be a bit fiddly to do so. From  StackExchange: Start placing figures on right-hand side column of first page we learn a trick that makes it easier!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
\documentclass{IEEEtran}
\usepackage{lipsum}

\title{My IEEE article}
\author{Author}

\begin{document}
\maketitle
\global\csname @topnum\endcsname 0
\global\csname @botnum\endcsname 0
\begin{abstract} \lipsum[1]\end{abstract}

\section{First Section}

As you can see in Fig~\ref{fig}

\begin{figure}
\centering
\fbox{A nice figure}
\caption{A nice figure}\label{fig}
\end{figure}

\lipsum[1-5]

\end{document}

Without

With

IEEE references

When writing papers using the  IEEE conference template (Shell, 2002) and BibTeX, you can use some interesting trickery to automatically control when et al. will be written out (Shell, 2007) instead of editing the .bib-file. From the  IEEE conference template we have that unless there are six authors or more we should print out the names of all the authors.

In the document itself, in the preamble, you need to add

1
\bstctlcite{IEEEexample:BSTcontrol}

At the top of your .bib-file you put this.

1
2
3
4
5
@IEEEtranBSTCTL{IEEEexample:BSTcontrol,
  CTLuse_forced_etal       = "yes",
  CTLmax_names_forced_etal = "6",
  CTLnames_show_etal       = "1"
}

• Setting CTLuse_forced_etal to yestruncates the list of author names and forces the use of “et al.” if the number of authors in an entry exceeds a set limit.
• CTLmax_names_forced_etal is the value of the maximum number of names that can be present beyond which “et al.” usage is forced. From the  IEEE conference template we get that this shall be 6.
• When et al. is forced, CTLnames_show_etal controls the number of names that are shown.

See (Shell, 2007) for complete list of parameters and default values.

Citations without line breaks

Citations and references is something that LaTeX and BibTeX do really well. A common way of citing is by writing word~\cite{source} so that there is a non-breaking space between the word and the brackets (assuming IEEE style here). However, when you cite multiple sources, the result is [7]–[9] or [10, 11] which could potentially introduce a line break within the citation itself! To fix this, we need to redefine the \citepunct and \citedash macros that determine what is inserted between the citations. In the first case, we just use a common non-breaking space ~, and in the second the \nolinebreak command prevents line breaking, and \hspace{0pt} allows the following text to start immediately, without inserting any additional space.

1
2
\renewcommand{\citepunct}{,~}
\renewcommand{\citedash}{]--\nolinebreak\hspace{0pt}[}

Typesetting et al.

I like to use a macro to write et al. where we add a penalty to a line break between the two parts.

1
\def\etal.{et\penalty50\ al.} % et al. with correct spacing

See  Should “et al.” have a thin or full, non-breaking vs. breaking space?.

Epsilon

In academic writing, particularly in mathematics, subtle nuances of notation can play a crucial role in conveying precise meanings. Sometimes using another symbol is just a sign of the author’s experience in the field. This holds true for symbols like “epsilon,” often denoted as either \(\epsilon\) (lunate form) or \(\varepsilon\) (inverted-3 form).

The choice between these two symbols illustrates a point that which symbol to use where might be a matter of discussion and source of confusion. See (Wikipedia contributors, 2023) and  \varepsilon vs. \epsilon for more information on the two versions.

Imaginary i

The possible ways of typesetting an imaginary \(\mathrm{i}\) are discussed in  How should imaginary numbers be typeset?.

I like to use an upright \(\mathrm{i}\), as in (ISO, 2009). Adding a small kern to distance it from an exponent, we can define it as

1
\newcommand{\di}{\mathrm{i}\mkern1mu} % imaginary i in roman and with correct spacing

Bonus tip

Not a LaTeX command, package or macro, but an extremely useful tool - Detexify is a web-based tool designed to help users find the LaTeX command for a specific symbol by drawing it. There is also a Mac OS application!

Related work

There are a few other sites with similar lists, and here are some of my favorites.

• The Art of LaTeX: Common Mistakes, and Advice for Typesetting Beautiful, Delightful Proofs (Zeng, 2023)
• Use Custom LaTeX Macros to Boost Your Writing Productivity (Valero, 2021)
• How to annoy your co-authors: a GitLab CI pipeline for LaTeX — automate compilation, linting, and diff generation on every commit

Conclusion

TeX and LaTeX are about as old as I am, and there are no shortage of packages and templates that you can use to craft elegant mathematical documents. There is also no shortage of “top ten” lists showcasing them. In this post we explored a few of my favorite commands and macros, please comment below with your favorites! For anyone wishing to dig deeper into mathematical typesetting, I would recommend (Knuth et al., 1989).

AI disclosure

This post was reviewed with AI-assisted quality tools (Claude Sonnet 4.6) to identify issues. All text is my own.

Why is this important?

In the fast-paced world of scientific research, the dissemination of knowledge is crucial for advancing our understanding of the world around us. Traditionally, the process of scientific publishing has been slow and rigid, often resulting in significant delays between the completion of research and its availability to the wider community. However, a groundbreaking development has been reshaping the landscape of academic publishing – the rise of pre-prints. Pre-prints are early versions of research papers made publicly available before formal peer review, offering researchers the opportunity to share their findings rapidly and to get early feedback. It has been shown that papers with pre-prints have a citation edge (Conroy, 2019; Xie et al., 2021), and that this effect is clear, immediate and long-lasting.

Consider this first

Before you continue, please consult the author information for the conference or journal that you will or have submitted to. After making sure that you are permitted to publish a pre-print, then you have to follow the rules with regards to the information that needs to be put on the first page, see IEEE Post-Publication Policies (Post-Publication Policies, 2023). But how exactly do you do that? As usual in LaTeX, there are about a million ways, here is one that I like (if you’re starting from a blank file, see bootstrapping your next LaTeX project; for more snippets like this one, see top LaTeX commands and macros for academic writing). Make sure you compile at least twice (which you already probably already do).

See Putting IEEE copyright on a document title page, How to add copyright notice (in a box with borders) at bottom of first page? and IEEEtran conference with \maketitle - copyright notice (in a box with borders) at bottom of first page? for more information on the subject.

Example.

After submitting a paper

We have to add the text (using the tikz package — see my roundup of essential LaTeX packages for more like it):

This work has been submitted to the IEEE for possible publication. Copyright may be transferred without notice, after which this version may no longer be accessible.

1
2
3
4
5
6
7
8
9
10
\usepackage{tikz}

\newcommand\submittedtext{%
  \footnotesize This work has been submitted to the IEEE for possible publication. Copyright may be transferred without notice, after which this version may no longer be accessible.}

\newcommand\submittednotice{%
\begin{tikzpicture}[remember picture,overlay]
\node[anchor=south,yshift=10pt] at (current page.south) {\fbox{\parbox{\dimexpr0.65\textwidth-\fboxsep-\fboxrule\relax}{\submittedtext}}};
\end{tikzpicture}%
}

After the paper is accepted and published

We have to add the text

© 20XX IEEE. Personal use of this material is permitted. Permission from IEEE must be obtained for all other uses, in any current or future media, including reprinting/republishing this material for advertising or promotional purposes, creating new collective works, for resale or redistribution to servers or lists, or reuse of any copyrighted component of this work in other works.

1
2
3
4
5
6
7
8
9
10
\usepackage{tikz}

\newcommand\copyrighttext{%
  \footnotesize \textcopyright \the\year{} IEEE. Personal use of this material is permitted. Permission from IEEE must be obtained for all other uses, including reprinting/republishing this material for advertising or promotional purposes, collecting new collected works for resale or redistribution to servers or lists, or reuse of any copyrighted component of this work in other works.}

\newcommand\copyrightnotice{%
\begin{tikzpicture}[remember picture,overlay]
\node[anchor=south,yshift=10pt] at (current page.south) {\fbox{\parbox{\dimexpr0.75\textwidth-\fboxsep-\fboxrule\relax}{\copyrighttext}}};
\end{tikzpicture}%
}

Finally

On the first page (for example after \maketitle, add \copyrightnotice or \submittednotice as needed.

In case we want the box to be red and be 2pt wide we can of course do that.

1
2
\renewcommand\fbox{\fcolorbox{red}{white}}
\setlength{\fboxrule}{2pt} % Set fbox rule width to 2pt

Introduction

In an earlier post, we looked at using Pandas (pandas development team, 2020; Wes McKinney, 2010 ) to produce nice looking tables with no manual steps. In this post we will take it one step further by adding sparklines (Tufte, 1986; Tufte, n.d.; Tufte, n.d.; Bissantz et al., 2007) to our table using the sparklines (Löffler et al., 2017) LaTeX package.

A sparkline is a very small chart, often in a text or in a table without axis or coordinates, that presents some measurement in an “intense, simple, wordlike graphics”. For example, The Dow Jones Industrial Average for February 7, 2006  (Licensed under CC BY-SA 2.5).

Example table using the Iris dataset from the `seaborn` library.

Sparklines are useful to show trends, highlight important events in time-series etc, which are otherwise hard to convey to a reader. They are especially useful when there are many such time-series and a regular figure would take up too much valuable space. In this post we will add them to a LaTeX table, but they can be used in running text, in spreadsheets and in many other situations.

The code

The Python code

First we will need some data - here we use weather data from Seattle, a Plotly (Plotly Technologies Inc., 2015) dataset. We will take this opportunity to clean it a little bit.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# First download the data from plotly's GitHub repository
df = pd.read_csv(
    'https://raw.githubusercontent.com/plotly/datasets/master/2016-weather-data-seattle.csv')

df['month'] = pd.to_datetime(df['Date']).dt.month

# we define a dictionary with months that we'll use later
month_dict = {1: 'January', 2: 'February',
              3: 'March', 4: 'April',
              5: 'May', 6: 'June',
              7: 'July', 8: 'August',
              9: 'September', 10: 'October',
              11: 'November', 12: 'December'}

df = df.sort_values("month")
df["datetime"] = pd.to_datetime(df.Date)
df = df.drop(["Date"], axis=1)
df = df.dropna()

Now we would like to group this data per month. Thereafter, we apply a magic function f.

1
2
3
4
df4 = (df
       .groupby("month")
       .apply(f).reset_index()
       )

The function f will calculate the mean, standard deviation and those important, but frankly boring, metrics. More interestingly it do one more thing - it will render a sparkline (Tufte, 1986; Tufte, n.d.; Tufte, n.d.; Bissantz et al., 2007).

1
2
3
4
5
6
7
8
9
def f(x):
    d = {}

    d['max'] = x['Mean_TemperatureC'].max()
    d['mean'] = x['Mean_TemperatureC'].mean()
    d['std'] = x['Mean_TemperatureC'].std()
    d['min'] = x['Mean_TemperatureC'].min()
    d['sparkline'] = sparkline(x)
    return pd.Series(d, index=['mean', 'std', 'min', 'max', 'sparkline'])

Rendering the sparkline consists of writing a sparkline environment to file, so we won’t cover it here. See the full Python code here and the sparklines (Löffler et al., 2017) LaTeX package documentation.

The LaTeX Code

Now that we have generated our table using Pandas, we need to include it in our document. See table.tex, where the included includes/macros.tex contains some libraries and macros that we need, see macros.tex.

Most importantly, we load the sparklines LaTeX package (Löffler et al., 2017). We also need to define a new command for a rectangle that is defined by its left and right values.

1
2
3
4
5
6
\def\sparkrectangleh #1 #2 {%
   \ifdim #1pt > #2pt
        \errmessage{The left corner #1 of rectangle cannot be lower than #2}%
   \fi
   {\pgfmoveto{\pgforigin}\color{sparkrectanglecolor}%
   \pgfrect[fill]{\pgfxy(#1, 0)}{\pgfxy(#2-#1,1)}}}%

Related work

spark (Blevins, 2013) is a LaTeX package for generating sparklines. ltxsparklines: Lightweight Sparklines for a LaTeX Document (Veytsman, 2017) is an interface for R to sparklines(Löffler et al., 2017).

Conclusion

Adding a table to your paper is a good idea. It is also a good idea to invest some time into making this table easy to read instead of just presenting a wall of numbers. In an earlier post, we looked at using Pandas (pandas development team, 2020; Wes McKinney, 2010 ) to produce nice looking tables where we highlighted some summary statistics. In this post we took this one step further by adding sparklines (Tufte, 1986; Tufte, n.d.; Tufte, n.d.; Bissantz et al., 2007).

Easily digested tables makes it easier to understand the idea and the message we are trying to convey. In fact there is some evidence (Huang, 2018) that the visual appearance of a paper is important and that improving the paper gestalt reduces risk of getting a paper rejected. In order to convey an idea efficiently we need to remove barriers so that the reader can understand this idea with as little cognitive effort as possible, and hopefully we have presented one way of achieving this here. We leave it to the reader to integrate this method into a Python package that is easy to use.

Introduction

Tufte argues that we should strive to have a high data to ink-ratio (Tufte, 1986) which means that we should strive to remove redundant graphical element that do not contribute to conveying our message. This applies to tables as well.

For typesetting tables in my scientific papers I use LaTeX with the booktabs (Fear & Els, 2020) package, one of my top 10 LaTeX packages. It is either my absolute favorite, or maybe a runner-up. Using booktabs goes a long way towards making beautiful tables with a high data to ink-ratio, but it’s a manual process.

Example figure produced with this method.

In this blog post we will explore automating tables using pandas (pandas development team, 2020; Wes McKinney, 2010 ) and booktabs for removing some unwanted ink from our tables. Building a pipeline for generating and including the tables into our LaTeX papers has the huge benefit of being reproducible. Because typesetting tables manually belongs in the 1980s.

Not saying you should group the data in this particular way, this post is just showing you could. In our post on adding sparklines we look into adding sparklines to our tables, and honestly you should read Tufte’s (Tufte, 1986) books before making tables anyways.

Using pandas to make a table

The first thing we need to do is to make a table from a dataset. We’ll look at the Iris dataset (Fisher, 1936) from the seaborn (Waskom, 2021) Python library.

Fisher’s 1936 paper printed this data as a hand-typeset “Table I” — fifty rows for each of three species. Here’s how the first few rows of Iris setosa looked in print:

These are the same measurements seaborn.load_dataset('iris') still ships today — the dataset every pandas tutorial reaches for is, quite literally, Fisher’s.

We could simply use the pandas function to_latex() to save a file containing the table in LaTeX format. pandas requires booktabs, but we can make this table even more beautiful with some simple tweaks.

Example table using the Iris dataset from the `seaborn` library.

We want a few things from this table: mean and standard deviation per measurement, with Length and Width as the two column groups (each under a \cmidrule) and Sepal/Petal down the rows, one species block per pair of rows separated by a dashed rule, and the largest mean per dimension highlighted in bold.

pandas.DataFrame.agg(["mean", "std"]) gives a 2-level column index (sepal_length, mean), (sepal_length, std), and so on. Each of those column names carries two facts at once — the organ (Sepal/Petal) and the dimension (Length/Width) — so we first split them on _ into a 3-level (Organ, Dimension, Statistic) column index. That split comes straight from the data’s own column names rather than being typed out by hand, so it stays correct even if the underlying dataset changes.

The layout choice matters here. The comparison worth inviting is sepal-vs-petal within a dimension. Here we compare a sepal length against a petal length, same units, same axis. Those belong in the same column, one row apart. Length-vs-width is a comparison of orthogonal dimensions we’d rather not invite, so we keep it split across two column groups. To get that, we stack() the Organ level down into the row index: rows become (Species, Organ), columns become just (Dimension, Statistic). This also collapses the header from three rows to two.

From there we use DataFrame.style rather than the plain to_latex() call, since we need per-cell formatting to_latex() alone can’t express. Styler.highlight_max() bolds the largest mean in each dimension column — no manual string patching required, unlike the version of this post from before pandas’ Styler-based LaTeX export existed. Styler.format_index() bolds the Length/Width group labels and swaps the plain mean/std labels for \mu/\sigma; those get wrapped in {} so siunitx’s S columns don’t try to parse them as numbers (the same trick as the Price ($) header in the booktabs example). We still use siunitx (Wright, 2009) — see Top LaTeX commands and macros for more examples — but its job is now just column alignment (S[table-format=1.2]), since Styler.format(precision=2) does the actual rounding on the Python side before the value ever reaches LaTeX.

Two gaps are left to patch in the rendered LaTeX. First, Styler.to_latex() prints the row-index names (Species, Organ) as their own header row; we fold those two labels into the empty leading cells of the \mu/\sigma row and drop the redundant line, bolding them to match the Length/Width headers, so the header is exactly the two rows we want. Second, it renders the grouped \multicolumn header without a \cmidrule underneath, so we add one with a small generic helper, cmidrules(), that walks the same MultiIndex the columns are built from and emits one rule per contiguous group — derived from the actual column structure rather than hardcoded. Finally, we separate each species block with a dashed \hdashline (from the arydshln package), so the two-row-per-species grouping reads at a glance.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "pandas==3.0.3",
#     "seaborn==0.13.2",
#     "jinja2==3.1.6",
# ]
# ///
import os

import pandas as pd
import seaborn as sns


def cmidrules(columns, level, start_col=1):
    """Emit one `\\cmidrule` per contiguous run of equal, non-empty labels
    at the given MultiIndex level. Generic over the actual column
    structure: add, remove, or rename groups and the rules follow.
    """
    rules = []
    run_start = None
    prev_key = None
    cols = list(columns)
    for i, col in enumerate(cols):
        pos = start_col + i
        key = col[: level + 1]
        label = col[level]
        same_run = key == prev_key and label != ""
        if not same_run:
            if run_start is not None and prev_key[-1] != "":
                span = str(run_start) + "-" + str(pos - 1)
                rules.append(r"\cmidrule(lr){" + span + "}")
            run_start = pos if label != "" else None
        prev_key = key
    if run_start is not None and prev_key[-1] != "":
        span = str(run_start) + "-" + str(start_col + len(cols) - 1)
        rules.append(r"\cmidrule(lr){" + span + "}")
    return "".join(rules)


if __name__ == "__main__":

    # Load data and calculate mean and std of each column, per species.
    agg = (sns.load_dataset('iris')
           .groupby("species")
           .agg(["mean", "std"])
           )

    # The (sepal_length, mean) columns pandas gives us carry two facts in
    # one name: the organ (Sepal/Petal) and the dimension (Length/Width).
    # Split them into a 3-level (Organ, Dimension, Statistic) column index,
    # straight from the column names so this stays correct if the data
    # changes.
    agg.columns = pd.MultiIndex.from_tuples(
        [(c[0].split("_")[0].title(),
          c[0].split("_")[1].title(),
          c[1]) for c in agg.columns],
        names=["Organ", "Dimension", "Statistic"],
    )

    # The comparison that matters is sepal-vs-petal *within* a dimension
    # (a sepal length against a petal length -- same units, same axis),
    # so those belong in the same column, one row apart. Length-vs-width
    # is a comparison of orthogonal dimensions we'd rather not invite, so
    # it's split across two column groups instead. Move Organ down into
    # the row index to make that layout: rows become (Species, Organ),
    # columns become (Dimension, Statistic).
    tbl = agg.stack(level="Organ", future_stack=True)

    # Fix the row order (stack sorts): Setosa/Versicolor/Virginica, each
    # with Sepal above Petal.
    species = ["setosa", "versicolor", "virginica"]
    tbl = tbl.reindex(
        pd.MultiIndex.from_product(
            [species, ["Sepal", "Petal"]], names=["Species", "Organ"]),
    )
    tbl.index = tbl.index.set_levels(
        [s.title() for s in species], level="Species")

    # Drop the column-axis names: with Organ moved into the rows, the
    # remaining levels are just Dimension/Statistic, and we don't want
    # those words printed as a header row -- the two-row header should be
    # Length/Width over mu/sigma, nothing more.
    tbl.columns.names = [None, None]

    mean_cols = [c for c in tbl.columns if c[1] == "mean"]

    styler = (
        tbl.style
        .format(precision=2)
        # Bold the largest mean in each dimension column -- Styler-native,
        # so no manual string patching of the rendered LaTeX is needed.
        .highlight_max(subset=mean_cols, props="bfseries:--rwrap;")
        # Bold the top-level (Length/Width) group labels.
        .format_index(
            lambda v: r"\textbf{" + v + "}" if v else v, axis=1, level=0)
        # mu/sigma read better than "mean"/"std" in a compact table; the
        # braces protect them from siunitx's S-column number parsing.
        .format_index(
            lambda v: r"{$\mu$}" if v == "mean" else
            r"{$\sigma$}" if v == "std" else v,
            axis=1, level=1)
    )

    column_format = "ll" + "S[table-format=1.2]" * len(tbl.columns)
    table = styler.to_latex(
        column_format=column_format,
        hrules=True,
        sparse_index=True,
        sparse_columns=True,
        multicol_align="c",
    )

    lines = table.splitlines()

    # pandas prints the row-index names (Species, Organ) as their own
    # header row, below the mu/sigma row and left of empty data cells.
    # Fold those two labels into the empty leading cells of the mu/sigma
    # row and drop the now-redundant names row, so the header is exactly
    # two rows: Length/Width, then Species | Organ | mu sigma mu sigma.
    n_index = tbl.index.nlevels
    index_names = list(tbl.index.names)
    for i, line in enumerate(lines):
        cells = line.rstrip(r"\ ").split("&")
        if [c.strip() for c in cells[:n_index]] == index_names:
            # Bold the row-axis header words (Species, Organ) to match the
            # bold Length/Width column headers; data values stay roman.
            name_cells = [r" \textbf{" + n + "} " for n in index_names]
            stat_cells = lines[i - 1].rstrip(r"\ ").split("&")
            merged = name_cells + stat_cells[n_index:]
            lines[i - 1] = "&".join(merged).rstrip() + r" \\"
            del lines[i]
            break

    # `to_latex` doesn't add a `\cmidrule` under the grouped Length/Width
    # header, so add one, computed from the same MultiIndex the columns
    # are built from. The two index columns (Species, Organ) push the
    # data columns to start at column 3.
    toprule_i = lines.index(r"\toprule")
    lines.insert(toprule_i + 2, cmidrules(tbl.columns, 0, start_col=3))

    # Separate each species block with a dashed rule (arydshln). Body rows
    # sit between `\midrule` and `\bottomrule`; there are two organ rows
    # per species, so a `\hdashline` goes after every second body row
    # except the last.
    midrule_i = lines.index(r"\midrule")
    bottomrule_i = lines.index(r"\bottomrule")
    body = lines[midrule_i + 1:bottomrule_i]
    rebuilt = []
    for i, row in enumerate(body):
        rebuilt.append(row)
        if i % 2 == 1 and i != len(body) - 1:
            rebuilt.append(r"\hdashline")
    lines = lines[:midrule_i + 1] + rebuilt + lines[bottomrule_i:]
    table = "\n".join(lines)

    # Write to file
    with open(
        os.path.splitext(
            os.path.basename(__file__))[0] + ".tbl", "w") as f:
        f.write(table)

At the end we are using the pandas function to_latex() to generate the LaTeX code and write the result to a file containing the tabular environment. The script pins its own exact dependencies (pandas==3.0.3, seaborn==0.13.2, jinja2==3.1.6) as inline script metadata, so uv run table.py reproduces the same environment with no separate install step.

Now we are ready to include the generated file into a LaTeX document.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
\documentclass[border=6pt]{standalone}

\usepackage{booktabs}
\usepackage{multirow}
\usepackage{array}
\usepackage{arydshln}
\usepackage{etoolbox}
\usepackage[round-mode=places,round-precision=2,detect-weight=true]{siunitx}
\usepackage{caption}
\renewcommand\arraystretch{1.2}

\setlength\dashlinedash{0.2pt}
\setlength\dashlinegap{1.5pt}
\setlength\arrayrulewidth{0.5pt}

\begin{document}
\begin{minipage}{\linewidth}
\centering
\robustify\bfseries
\captionof{table}{A generated table}
\input{table.tbl}
\end{minipage}
\end{document}

Automation

To automate this build, we use the following Makefile. It pins the LaTeX build to a specific texlive/texlive Docker image by digest so that it reproduces the same TeX Live install regardless of when or where you run it, without needing LaTeX installed on the host at all.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
SOURCES=$(wildcard *.py)
SOURCES:=$(filter-out rasterize.py,$(SOURCES))
PNG_OBJECTS=$(SOURCES:.py=.png)

# Pinned by digest (not :latest) so this actually reproduces the same
# TeX Live install rather than "whatever's current when you run it".
TEXLIVE_IMAGE=texlive/texlive@sha256:de561c78594d62b2d0fdb3d26c0fe61644a3b6ae12415bb41a770e55cce615ea
DOCKER_TEXLIVE=docker run --rm -v "$(CURDIR)":/work -w /work $(TEXLIVE_IMAGE)

all: $(PNG_OBJECTS)

%.tbl: %.py
	uv run $<

%.pdf: %.tex %.tbl
	$(DOCKER_TEXLIVE) pdflatex -interaction=nonstopmode $<

%.png: %.pdf
	uv run rasterize.py $< $@

clean:
	-rm -f *.tbl *.pdf *.aux *.log $(PNG_OBJECTS)

.PHONY: all clean

Running make in the tables directory does the whole pipeline: uv run table.py generates the .tbl file, pdflatex (inside the pinned Docker container) compiles table.tex into a .pdf.

Related Work

(Kalinke, 2020) was the inspiration for this post. The method used herein to make numbers bold included code for formatting the numbers. In this work we use siunitx instead to do the formatting.

In R we can use packages xtable or kableExtra to achieve similar results. In particular, kableExtra is very capable and the documentation (Zhu, 2020) has many interesting examples.

The entire library of work by Edward Tufte is hugely inspirational to us. (Tufte, 1986) tells us not to put too much ink on the paper.

FAQ

Why use Docker instead of just installing TeX Live locally?

So the exact same TeX Live install reproduces on any machine, pinned by image digest rather than :latest. It also means you don’t need LaTeX installed on your host at all to regenerate the figures.

Why pin exact package versions instead of using the latest pandas and seaborn?

So someone else running this in a year gets the same output we did, not whatever the latest release happens to do differently. The pins live as inline PEP 723 script metadata in the file table.py itself, so uv run table.py reproduces the exact same environment with no separate install step.

What actually broke when upgrading to pandas 3.x?

Two things, found by actually running the upgrade rather than assuming it would work: to_latex() now routes through Styler internally and needs jinja2 as an optional dependency, and its escape parameter default flipped from True to effectively no-escaping, which silently broke a script that relied on the old default.

Conclusion

We have looked at how to make tables generated by pandas to look more professional by using siunitx and some tweaks. The Makefile we created should go into the tables directory of your manuscript so that you can use make -C tables all as a dependency to your normal make report target.

Easily digested tables makes it easier to understand the message we are trying to convey. In fact there is some evidence (Huang, 2018) that the visual appearance of a paper is important and that improving the paper gestalt reduces risk of getting a paper rejected.

Once you have tables you’re happy with, adding sparklines to them is a natural next step to make trends easier to read at a glance.

AI disclosure

This update involved AI-drafted writing: the table.py/table.tex/Makefile/rasterize.py pipeline and the technical walkthrough explaining it (the MultiIndex/Styler/cmidrule mechanism, the pandas 3.x breakage, the FAQ) were developed with AI assistance (Claude Sonnet 5) under my direction, including actually running the upgrade, hitting real pandas/siunitx compatibility breaks, and fixing them rather than just describing them secondhand. The historical framing, editorial calls and final review are mine.

Introduction

Setting up a new LaTeX project is usually a boring process where I do manual repetitive steps such as creating a directory structure, add file stubs, copy the Makefile from some old project, and more.

I like to use git for version control of LaTeX documents, so setting up a git repository is an important step. I do this even if I am working alone on a project. Version control allows me to track my progress, have a backup, and make sure the document is completely reproducible from raw data. The principle of Reproducible Research (Buckheit & Donoho, 1995; Claerbout & Karrenbach, 1992; Association for Computing Machinery (ACM), n.d.) is to make data and computer code available for others to analyze and criticize.

A good open source repository is exercisable and complete (Monperrus, 2018; Association for Computing Machinery (ACM), n.d.). This means that it must be possible to fully reproduce the document, down to the last pixel, from running a single script in the repository. In How to annoy your co-authors: a Gitlab CI pipeline for LaTeX we took a look at this can be done - but there were many manual steps which we will automate in this post.

Here are a few things I always do at the start of a new LaTeX project.

• Create a directory structure (for chapters, figures, data, bibliography, …),
• Add a .gitignore default for LaTeX;
• Create a main.tex-file from a LaTeX template, usually from a conference template;
• Populate said file with author, working title;
• Initialize git locally;
• Create remote git repository on Gitlab, or a Gitlab CE instance;
• Add a Makefile, configure it to use the compiler that the template dictates;
• Add a .gitlab-ci.yml (see How to annoy your co-authors: a Gitlab CI pipeline for LaTeX);
• Create a Sublime project;
• Add a README.md with some build instructions for my co-authors and
• Perform a test compilation of the entire project.

Using a project template

What if we can run a single command to set up a new project? For this we can use [cookiecutter](https://github.com/cookiecutter/cookiecutter) (Roy Greenfeld et al., 2020). cookiecutter is a command-line utility that creates projects from cookiecutters which are project templates.

Using a cookiecutter is easy. We can just run

1
cookiecutter gl:martisak/latex-template

Running cookiecutter

You will need a Gitlab account. Then you need to add these environment variables, for example by adding this to your .zshrc. Read more on how to create a private Gitlab token.

1
2
3
export GITLAB_API_PRIVATE_TOKEN=<your private token>
export GITLAB_API_USERNAME=<your username>
export GITLAB_URL=gitlab.com

Of course, some fields will always be the same (such as your name), so we can add our defaults to ~/.cookiecutterrc.

1
2
3
4
5
6
7
8
default_context:
    full_name: "Martin Isaksson"
    email: "m@cyberdyne.se"
    gitlab_username: "martisak"
    affiliation: "Cyberdyne Systems"
    department: "AI lab"
    paper_title: "Lorem ipsum"
cookiecutters_dir: "~/.cookiecutters/"

After you have run this cookiecutter template, you will have a working directory that looks like this.

├── Gemfile                         # For the test stage
├── Gemfile.lock                    # For the test stage
├── Makefile                        # For building
├── README.md                       # A stub README
├── chapters
│   ├── conclusion.tex              # A chapter in LaTeX
│   └── introduction.tex            # A chapter in LaTeX
├── figures
│   ├── Makefile                    # A Makefile for building the figures
│   ├── example.py                  # Python code for plotting
│   └── requirements.txt            # Requirements for the figure stage
├── lorem-ipsum.sublime-project     # A Sublime project file
├── lorem-ipsum.tex                 # This is the main LaTeX file
├── references
│   └── main.bib                    # References in bibtex
└── spec
    └── pdf_spec.rb                 # For the test stage

We see a lot of auxiliary files for testing and for setting up a Sublime project. If you have a better directory structure, feel free to fork my cookiecutter and make it better!

Related work

There are many existing cookiecutters for creating LaTeX documents. However, I didn’t find one that fitted my needs, so I made my own.

Yeoman (Osmani et al., 2020) provides another generator ecosystem, is language agnostic and can be used to generate any kind of scaffolding. However, since it is Node.js-based it could be argued that it is more geared towards web development. It is very extensible and it is easy to create custom templates, assuming knowledge of Node.js.

An interesting feature of Yeoman generators is that it allows for sub-generators. These can be used for example to generate new chapters in our documents.

Conclusion

So now we have a good starting point that you can use for your awesome next paper — all you need to do is fill in the blanks.

A remaining manual step is to find and copy the LaTeX template. If you always use the same template, this can be included in the cookiecutter template. In a future post we will look into how to use Pandoc and Markdown which will make choosing and switching templates easier.

Introduction

Scientific paper submission is a sort of empirical risk minimization problem where we want to minimize the risk that our paper will be rejected. We don’t have access to the true risk, but have to measure this empirical risk in some other way.

There are many factors that affect this risk - the most obvious being the quality of the content. However, with the increasing number of submissions the first impression of a reviewer is also increasingly important. In order for a reviewer to be able to assess the real quality of our paper, we must first avoid that the reviewer throws our paper into the recycling bin. A paper that successfully avoids the recycling bin should continue to convey a positive feeling so that the reviewer tries to find a reason to accept the paper rather than the opposite.

(Huang, 2018) trained a classifier to reject or accept a paper based solely on the visual appearance of a paper and found a few parameters that indicate good papers. One such interesting aspect is that we should fill all the available pages, which gives the impression of a more well-polished paper. In this post we will use this metric as a proxy for quality and minimize the empirical risk that our paper is rejected.

At submission time we find ourselves fighting the automated PDF checks of the publisher (see How to beat publisher PDF checks with LaTeX document unit testing) and we are changing figure sizes and other parameters, compiling and checking the output in order to fill the last page entirely and not have the content spill over to a new page. This process is frustrating, labor intensive, slow, and boring, not to mention error-prone.

The stuff from which nightmares are made - content spilling over to the fourth page.

A situation many of us recognize, regardless of where we are in our academic careers. With permission from "Piled Higher and Deeper" by Jorge Cham.

One large step towards a solution to this was proposed by (Acher et al., 2018) in which the authors annotate the LaTeX source with variability information. This information can be numerical values on figure sizes, or boolean values on options or whether to include certain paragraphs. In their work they formulate the learning problem as a constrained binary classification problem to classify into acceptable and non-acceptable configurations so that acceptable solutions can be presented to the user.

Here, we instead formulate this problem as a constrained optimization problem, where the constraints are defined by the automated PDF checks and the optimization is defined by proxy metrics such as amount of white space on the last page.

To find the optimal variable values we will use Ray Tune (Liaw et al., 2018). Ray Tune allows us to run parallel, distributed, LaTeX compilations and provides a large selection of search algorithms and schedulers.

Contributions

This work is inspired by three papers and develop these foundations in the following ways:

• We define and implement a proxy-metric for paper quality, based on findings from (Huang, 2018), that can be directly measured on a PDF-file. See Our LaTeX manuscript and a proxy quality metric.
• We show how a LaTeX document can be annotated using variability information following ideas from (Acher et al., 2018) but without using a preprocessor. See Annotating the LaTeX source code.
• We formulate a constrained non-convex objective function and proceed to solve it efficiently using Ray Tune (Liaw et al., 2018). See Optimization problem and Hyperparameter search.

Methods

The LaTeX manuscript and a proxy quality metric

We again turn the example from the IEEE Manuscript Templates for Conference Proceedings to test these methods. The flushend package is used so that the last column is balanced. We also add another figure and vary each of the figure widths from zero width to one line widths - this will affect the amount of white space on the last page. A visualization of the last page white space can be seen in the figure below.

We use the example from the IEEE Manuscript Templates for Conference Proceedings to test these methods.

The cost we optimize is based on the bottom margin on the last page and depends on some input variables, such as figure widths.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def calculate_cost(self):

        pdf_document = fitz.open(self.pdffile)

        if pdf_document.pageCount > 3:
            return 10000

        page1 = pdf_document[-1]

        full_tree_y = IntervalTree()
        tree_y = IntervalTree()

        blks = page1.getTextBlocks()  # Read text blocks of input page

        # Calculate CropBox & displacement
        disp = fitz.Rect(page1.CropBoxPosition, page1.CropBoxPosition)

        croprect = page1.rect + disp
        full_tree_y.add(Interval(croprect[1], croprect[3]))

        for b in blks:  # loop through the blocks
            r = fitz.Rect(b[:4])  # block rectangle

            # add dislacement of original /CropBox
            r += disp
            _, y0, _, y1 = r

            tree_y.add(Interval(y0, y1))

        tree_y.merge_overlaps()

        for i in tree_y:
            full_tree_y.add(i)

        full_tree_y.split_overlaps()

        # For top and bottom margins, we only know they are the first and
        # last elements in the list
        full_tree_y_list = list(sorted(full_tree_y))
        _, bottom_margin = \
            map(
                get_interval_width,
                full_tree_y_list[::len(full_tree_y_list) - 1]
            )

        return bottom_margin

To calculate our metric it will be required to find the dimensions of each page and each bounding box within the last page (Isaksson, 2020).

The basic algorithm is as follows: We loop over each bounding box within the last page. For every bounding box we add an interval to an interval tree for the dimensions in the y-direction. We can the use this to find the difference between the page dimensions and the extent of the bounding boxes on the page. For this we will use the Python package intervaltree (Leib Halbert & Tretyakov, 2018).

The implementation is discussed more in How to beat publisher PDF checks with LaTeX document unit testing.

Annotating the LaTeX source code

For this example, we will vary the width of two figures, in terms of \linewidth. The value of each variable is sampled from \(\mathcal{U}\left(0,1\right)\).

To make things easy for us, we write variable definitions to a macros.tex file and input this file in our LaTeX document preamble. The file contains for example the definitions for two figure width.

1
2
\def\figonewidth{0.602276759098264}
\def\figtwowidth{0.5600851582135735}

These variables are then used in the document to set each figure width individually. As an example, here is the first figure:

1
2
3
4
5
6
\begin{figure}[htbp]
\centering
\includegraphics[width=\figonewidth\linewidth]{fig1.png}
\caption{Example of a figure caption.}
\label{fig1}
\end{figure}

In this way we can avoid using a pre-processor, and we can use only LaTeX code in the document itself. Note that we do not specify the domain of these variables in the LaTeX-code, but define this in the Python-code instead, see Defining the experiment. In our work, these variables can be of any data type that is supported in LaTeX and Python.

Optimization problem

Our objective function is based on the last page bottom margin \(b(\boldsymbol{\theta})\) that is a function of our variables \(\boldsymbol{\theta} = \left[\theta_0, \ldots, \theta_n\right]\). We add a L2-regularization term on \(1-\theta_k\) for each variable \(\theta_k \in \boldsymbol{\theta}\) since we want to favor solutions with larger \(\theta_k\), solutions that have similar \(\theta_k\) and to make the math look more impressive. We negate the objective function and maximize it. If requirements set out in How to beat publisher PDF checks with LaTeX document unit testing are not met, we add a penalty to \(l(\boldsymbol{\theta})\).

The optimal variables \(\boldsymbol{\theta}*\) are then

where

As we can see in the figures below, the objective function \(l(\bf{\theta})\) is non-convex and the added L2-regularization gives us solutions that tend to have larger figure widths, which is what we want.

Note that we cannot tune the hyper-parameter \(\lambda\), so we set it to \(2\pi\), because that’s the most beautiful number known to man.

Hyperparameter search

Defining the tasks

We will use Ray Tune (Liaw et al., 2018) for searching this parameter space (the parameters we are defining here are of course not hyper-parameters). We begin with an exhaustive grid-search over the entire search space which is here \(v \in [0, 1]\, \forall \theta_k \in \boldsymbol{\theta}\). Since we have two figures each with a variable width we have \(\vert\boldsymbol{\theta}\vert = 2\). Performing a grid-search over each of the variables divided into 51 possible values gives us 2601 paper variants to compile. Each of the paper compilations consists of five steps;

1. Copy the LaTeX code to a temporary directory.
2. Sample variables and write to file macros.tex,
3. Clean document directory using latexmk and
4. Compile document with latexmk.
5. Measure quality proxy-metrics on PDF file.

The average execution time for each task is 5.46 seconds, and we can run 8 of these in parallel. This means that an experiment takes roughly 30 minutes on my laptop. With Ray Tune we also have the option to run this using a much larger set of machines if needed. Compilation using more than one CPU per worker is shorter, but since we can run fewer in parallel the total execution time is longer.

Document compilation (really Ray worker execution) time PDF, because measuring things makes it feel more like science.

Search algorithm

However, running an exhaustive grid search is not needed as we can use one of the search algorithms provided by Ray Tune instead. Specifically we will use a Asynchronous HyperBand scheduler with a HyperOpt search algorithm. HyperOpt (Bergstra et al., 2013) is a Python library for optimization over awkward search spaces. In our use-case we have real-valued, discrete and conditional variables so this library works for us, but we will not evaluate its performance on our objective function and can therefore not claim that it is the best search algorithm for this particular problem.

Defining the experiment

We define our experiment directly in the code, for simplicity. First we will define our search space. Here we sample each variable from \(\mathcal{U}(0,1)\).

1
2
3
4
space = {
    'var-figonewidth': hp.uniform('var-figonewidth', 0, 1),
    'var-figtwowidth': hp.uniform('var-figtwowidth', 0, 1),
}

We can then optionally give a few starting guesses. We will give to guesses that both lie on the diagonal where both figure widths are equal.

1
2
3
4
current_best_params = [
    {'var-figonewidth': .75, 'var-figtwowidth': .75},
    {'var-figonewidth': .65, 'var-figtwowidth': .65}
]

Lastly we will define our Ray Tune experiment and run it.

1
2
3
4
5
6
7
8
9
10
11
12
13
algo = HyperOptSearch(space, metric="score", mode="max",
                      points_to_evaluate=current_best_params)

scheduler = AsyncHyperBandScheduler(metric="score", mode="max")

tune.run(
    MyTrainable, name=config["name"],
    scheduler=scheduler, search_alg=algo,
    config=conf, verbose=1,
    resources_per_trial=config["resources"],
    num_samples=num_samples_per_axis,
    reuse_actors=True,
    loggers=DEFAULT_LOGGERS + (MLFLowLogger, ))

See the complete source code in the repository.

Results

Track and visualize results

We can visualize the results of the hyper-parameter search using Tensorboard (Abadi et al., 2015) in a Docker (Merkel, 2014) container using the following command:

1
docker run -v [RAY_RESULTS_PATH]:/tf_logs -p 6006:6006 tensorflow/tensorflow:2.1.1 tensorboard --bind_all --logdir /tf_logs

Visualizing LaTeX compilation metrics via Ray Tune using Tensorboard in Docker ticks all the nerd-boxes.

Ray Tune integrates well with MLFlow. Here we use the Parallel Coordinates Plot to visualize invalid solutions.

The Ray dashboard provides a minimal dashboard to monitor the workers.

MLFlow (Databricks, 2020) is a Python package that can be used to for example track experiments and models. Here we use it to visualize the hyper-parameters and the corresponding objective function score. The MLFLow UI can be started simply with mlflow ui.

Solutions found

The objective function with L2-regularization visualized with solutions searched by HyperOpt.

Objective function score as a function of figure widths when both figures are set to equal width. Note that the optimal solution is not the maximum figure width that still satisfies the constraints.

For the specific objective function illustrated here, we could potentially use a variant of gradient descent. However, as we add more variables, the search space becomes more complicated.

Using Ray Tune has a major advantage in that it is easy to parallelize our document compilation on a large set of workers and the API makes changing scheduler and search algorithm a breeze.

Related work

In the inspiring “VaryLaTeX: Learning Paper Variants That Meet Constraints” paper (Acher et al., 2018) the authors annotate LaTeX source with variability information and construct a binary classification problem where the aim is to classify a configuration as fulfilling the constraints or not. The classifier can be used to present a set of configurations to the user that then can pick an aesthetically pleasing configuration out of the presented set. This is a much more complete solution that the one presented in this post. A potentially interesting addition to their work is to annotate the configurations with a score, that can be used to sort a potentially large set of valid configurations. See their Github repository.

(Huang, 2018) constructs a binary classification tasks to predict if a paper is good or bad, based on the Paper Gestalt of a paper, i.e. only the visual representation of the paper. The paper goes on to discuss how to improve the Paper Gestalt, for example adding a teaser figure, a figure on the last page and filling the complete last page. The latter can be numerically estimated, which is what we based this blog post on.

Limitations, discussions and future work

The experiments in this blog post aim to produce a single paper that fulfills all publisher constrains and requirements. This single paper is optimized in terms of last page white space, which disregards pretty much everything that makes a paper great and should therefore be used with caution.

There are other metrics that we can use for optimization, for example the number of words, data density (Tufte, 1986). We can add more variability by considering figure placement, microtype options (Schlicht, 2019), and more.

The optimization can be added as a stage in a LaTeX pipeline as outlined in How to annoy your co-authors: a Gitlab CI pipeline for LaTeX

In this post we viewed the parameters as hyper-parameter and used Ray Tune, which is made for tuning hyper-parameters . The parameters we used are in fact not hyper-parameters, and other frameworks and solvers could have been used. However, we find that two aspects of Ray Tune makes it a good candidate for this problem; it’s is simple to use and it can parallelize these tasks efficiently.

Conclusions

While the last page white space is obviously a bad proxy for paper quality, we have shown that we can remove a part of paper writing that is labor intensive, slow, boring, and error-prone. We combined three pieces of work that I find ingenious in their own rights to make a complicated machine to optimize a parameter that maybe doesn’t matter all that much - but, hey, it was fun!

Acknowledgment

This post has been in the making for a very long time, but it was a comment on How to beat publisher PDF checks with LaTeX document unit testing by @mathieu_acher that finally made me sit down and make this happen. Thank you!

Introduction

Recently, I submitted a scientific paper to an IEEE conference. For a manuscript to be accepted by the publishing system Editor's Assistant (EDAS) it has to pass an unknown number of unspecified test cases. This took far too many attempts, as can be seen in the figure to the right.

Here is one error that I received.

The gutter between columns is 0.165 inches wide (on page 3), but should be at least 0.2 inches.

Nowhere did it say that the gutter should be 0.2 inches. Another IEEE conference that I submitted to had a smallest gutter width of 0.16 inches, and it seems that this is up to each conference chair to decide. As you can imagine, when trying to fix this, some text will spill over to the next page so then the document is over the page-limit. Uploading a document many times is a pain.

In this post we will create a series of test cases to catch these errors locally before submitting.

The publishing system gave this message for the final version of the manuscript that was uploaded without problems.

The paper has 6 pages, has a paper size of 8.5x11 in (letter), is formatted in 2 columns, with a gutter of 0.201 inches (smallest on pg. 5), the most common font size is 9.96 pt, the average line spacing is 11.95 pt, margins are 0.673 (L) x 0.653 (R) x 0.701 (T) x 0.990 (B) inches, uses PDF version 1.7 and was created by TeX.

It can take many attempts to pass EDAS PDF checks.

Template

The techniques we use here can of course be applied to any PDF document. We will here take a look at a two-column conference paper since this provides us with a number of interesting things to test that other formats don’t.

We use the example from the IEEE Manuscript Templates for Conference Proceedings to test these methods.

The IEEE Manuscript Templates for Conference Proceedings example is particularly interesting due to the multiple author bounding boxes. We can download the template and an example document and compile it directly to produce the PDF that we will run our test cases on.

Test cases

Requirements and setup

We need to understand the requirements of the publishing system. Some of these requirements can be found on the conference website. For example, we see that the page limit is 6 pages in a 10 point font, and that we should use the IEEE Manuscript Templates for Conference Proceedings template. Other than that, there is no more useful information.

Here are the requirements, gathered from various sources, that we are going to write test cases for in this post.

Some of them, for example the margins are tweaked after a paper that passed the test had margins narrower than the one suggested by the IEEE requirements.

Test framework

For the test framework we will use the popular Python test framework pytest (Krekel et al., 2004) with the PyMyPdf (McKie & Liu, 2020) package to interact with the PDF file. The entire script can be found in the Gitlab repository How to beat publisher checks with LaTeX document unit testing.

We setup our requirements from the table above as follows in config.yml, in YAML format.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
metadata:
    creator: "TeX"
    producer: "pdfTeX-1.40.21"
    encryption: null
    min_version: 1.4

margins:
    min_gutter: 0.16                        # in
    min_lr_margin: 0.625                    # in
    min_top_margin: 0.65                    # in
    min_bottom_margin: 1                    # in

pages:
    min_pages: 1
    max_pages: 6
    papersize: [0.0, 0.0, 612.0, 792.0]     # Letter, pts

max_file_size: 41943040                 # 40 MB
skip_boxes_on_first_page: 12            # test this
required_text: []

Annotations

It would be a bit embarrassing to submit a file with annotations still in it, so let’s start by checking that we didn’t add any.

1
2
3
4
5
6
7
8
def test_annotations(pdf_document):
    """
    Test that there are no annotations.
    """

    for page1 in pdf_document:
        annotations = list(page1.annots())
        assert not annotations

Metadata

For the metadata fields creator, producer, author, title, subject, encryption and keywords we can simply check that the result is as expected by comparing to what we defined in the configuration file config.yml.

1
2
3
4
5
6
7
8
9
10
11
12
13
def test_metadata(pdf_document, config):
    """
    For each of the specified fields, check that the result
    is as expected.
    """

    metadata_fields = ["author", "creator", "title",
                       "subject", "keywords", "producer",
                       "encryption"]

    for field in metadata_fields:
        assert pdf_document.metadata.get(
            field, None) == config["metadata"].get(field, None)

For the PDF version, we usually specify a minimum version so we define a separate test case for that. Should we need to change this in the document, we can add \pdfminorversion=7 to our preamble.

1
2
3
4
5
6
7
8
def test_pdf_version(pdf_document, config):
    """
    Test that the PDF version is at least the specified
    """

    version = float(pdf_document.metadata.get("format", None).split(" ")[1])

    assert version >= config.get("min_version", 1.4)

Number of pages

It is quite common that a conference and a journal has a maximum number of pages. The lowest number of pages is of course one, but we’d most likely want to use every inch of space available to us.

1
2
3
4
5
6
7
8
9
def test_pages(pdf_document, config):
    """
    Test that the number of pages is between
    the minimum and the maximum number of pages.
    """

    assert config.get("min_pages", 1) <= \
        pdf_document.pageCount <= \
        config.get("max_pages", 5)

Dimensions

To calculate margins and other dimensions it will be required to find the dimensions of each page and each bounding box within each page. In the process we also find the number of columns.

The basic algorithm is as follows: We first loop through each page and each bounding box within that page. For every bounding box we add an interval to an interval tree - one for the dimensions in the x-direction, and one for the dimensions in the y-direction. For this we will use the Python package intervaltree (Leib Halbert & Tretyakov, 2018).

Interval trees (contributors, 2020) are interesting in their own right, but we won’t go into the details of how they work. Here it is enough to say that we can do operations on these interval trees to find the widths of gutters and margins easily.

For each new bounding box we find, we add the interval between the left edge and the right edge to one interval tree. After we have done this for all bounding boxes we merge the overlap of these intervals so that we are left with a list of non-overlapping intervals. We do this both for the x-dimension (illustrated below in blue) and the y-dimension (illustrated below in red).

The first page with overlayed non-overlapping bounding boxes in the x-direction in blue and non-overlapping bounding boxes in the y-direction in red. To find the two columns, the 12 first bounding boxes were skipped.

The second page with overlayed non-overlapping bounding boxes in blue. There is only one non-overlapping bounding box in the y-direction.

The first and the second page illustrate how complicated the bounding box analysis can be.

We see that the first page contains things like the title and author blocks that straddle the gutter. This will affect how we can detect the columns and calculate the width of the gutter. Here, we take an easy way out and just skip the first 12 bounding boxes. We find the number of bounding boxes to skip by counting the red boxes in the figure. This problem also extends to pages where a top figure spans the two columns.

After we have calculated the non-overlapping intervals we can easily calculate the width of these. For a two column document, the first interval is the left margin, the second is the first column and the third interval is the gutter. Since the margin and gutter is different on each page, we assert that all of them meet the requiements.

Should the gutter be too narrow (something that always happens way too often) we can tweak the column separation with

1
\setlength{\columnsep}{0.235in}

Another thing that will effect this is microtype and it’s various options, for example protrusion.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def test_dimensions(pdf_document, config):
    """
    This test case loops through pages and checks
        - paper size
        - gutter width
        - number of columns

    Finally it saves a document with the found columns and bounding boxes
    overlayed.
    """

    blue = (0, 0, 1)

    count = 0
    for page1 in pdf_document:

        full_tree_x = IntervalTree()
        full_tree_y = IntervalTree()
        tree_x = IntervalTree()
        tree_y = IntervalTree()

        blks = page1.getTextBlocks()  # Read text blocks of input page
        img = page1.newShape()  # Prepare contents object

        # Calculate CropBox & displacement
        disp = fitz.Rect(page1.CropBoxPosition, page1.CropBoxPosition)

        croprect = page1.rect + disp
        full_tree_x.add(Interval(croprect[0], croprect[2]))
        full_tree_y.add(Interval(croprect[1], croprect[3]))

        # This tests paper size
        assert list(croprect) == config["pages"].get("papersize")

        for b in blks:  # loop through the blocks
            r = fitz.Rect(b[:4])  # block rectangle

            # add dislacement of original /CropBox
            r += disp
            x0, y0, x1, y1 = r

            # Dangerous!
            if count > config.get("skip_boxes_on_first_page", 2):
                tree_x.add(Interval(x0, x1))
                tree_y.add(Interval(y0, y1))

            count += 1

        tree_x.merge_overlaps()
        tree_y.merge_overlaps()

        # Must be two columns
        assert len(tree_x) == 2

        for intrv in tree_x:

            a = [intrv[0], tree_y.begin(), intrv[1], tree_y.end()]

            re = fitz.Rect(a)
            img.drawRect(re)
            img.finish(width=1, color=blue)
            img.commit(overlay=True)  # store /Contents of out page

        for i in tree_x:
            full_tree_x.add(i)

        full_tree_x.split_overlaps()

        for i in tree_y:
            full_tree_y.add(i)

        full_tree_y.split_overlaps()

        # If there are two columns, the gutter should be in the middle.
        # Margins are the first and last intervals, the ignored parts
        # are the left and right columns.
        left_margin, _, gutter, _, right_margin = \
            map(get_interval_width, list(sorted(full_tree_x)))

        # For top and bottom margins, we only know they are the first and
        # last elements in the list
        full_tree_y_list = list(sorted(full_tree_y))
        top_margin, bottom_margin = \
            map(
                get_interval_width,
                full_tree_y_list[::len(full_tree_y_list) - 1]
            )

        assert gutter > config["margins"].get("min_gutter", 0.2)
        assert left_margin > config["margins"].get("min_lr_margin", 0.625)
        assert right_margin > config["margins"].get("min_lr_margin", 0.625)
        assert top_margin > config["margins"].get("min_top_margin", 0.75)
        assert bottom_margin > config["margins"].get("min_bottom_margin", 1)

    # save output file
    pdf_document.save("layout.pdf",
                      garbage=4, deflate=True, clean=True)

Links and bookmarks

Links and bookmarks are created by hyperref. I’d like to keep this package, but set the output to draft for the final publication in order to disable it.

1
2
3
4
\usepackage[
    final,
    bookmarks=true
]{hyperref}

Testing that we have not links or bookmarks in our document is simple, we just make sure that the list of links on each page is empty and that the bookmark list is empty.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
def test_no_links(pdf_document):
    """
    Test that no links appear on any page.
    """

    for page1 in pdf_document:
        assert len(page1.getLinks()) == 0


def test_no_bookmarks(pdf_document):
    """
    Test that the document does not contain bookmarks
    """

    assert len(pdf_document.getToC()) == 0

File size

The system that we upload our document to has a limit on the size of document, and it is easy to test for this.

1
2
3
4
5
6
def test_file_size(pdf, config):
    """
    Test that the filesize is below the limit.
    """

    assert Path(pdf).stat().st_size < config.get("max_file_size", 0)

Spelling and grammar

To test spelling and grammar I use LanguageTool, textidote and vale. However, the number of false positives are staggering and they are unusable for automatic testing. This is also a larger topic that deserves an in-depth analysis.

Title in title case

The title shall be in title case. In this regard EDAS follows the Associated Press Stylebook and the New York Times style book. These state that only short prepositions and articles with four letters or less are lowercase.

The Python package titlecase uses a wordlist from New York Times Manual of Style to decide what words shall be lowercase.

1
2
3
4
5
6
7
8
9
def test_title_case(pdf_document):
    """
    Test that the title (first block on first page)
    is title cased properly.
    """

    page1 = pdf_document.loadPage(0)
    title = page1.getTextBlocks()[0][4]
    assert title == titlecase(title)

Required text

For my work I am required to put in a pre-defined sentence in the acknowledgment-section so I want to test that the document contains this string. This test case can easily be modified to detect black-listed words.

1
2
3
4
5
6
7
8
9
10
11
def test_required_text(pdf_document, config):
    """
    Test that each required text is found in the document.
    """

    for text in config.get("required_text", []):
        hits = 0
        for page1 in pdf_document:
            hits += len(page1.getTextPage().search(text))

        assert hits > 0

Embedded fonts

We can test that the fonts are embedded by trying to extract them from each page. This can be optimized since each font will be extracted several times. At the same time we will check that the font is not a Postscript Type 3 font, since these can be bitmap fonts. This can for example happen when using matplotlib since matplotlib will use Type 3 fonts per default. See (Oaks, 2014) or Publication ready figures for ways to get around this.

1
2
3
4
5
6
7
8
9
10
11
def test_embedded_fonts(pdf_document):
    """
    Check that all fonts are extractable. This will at least loop through
    the embedded fonts and check their types.
    """

    for page in pdf_document:
        for f in page.getFontList():
            _, ext, fonttype, _ = pdf_document.extractFont(f[0])
            assert fonttype in ["TrueType", "Type1"]
            assert ext != "n/a"

Results of the test cases

We can compile the example document and run our test suite with

1
2
make -C example dist-clean compile
pytest -v --pdf example/Conference-LaTeX-template_10-17-19/conference_101719.pdf

This is the same as running make render test (using Docker containers), which gives us these results.

1
2
3
4
5
6
7
8
9
10
11
test_pdf.py::test_annotations PASSED    [  9%]
test_pdf.py::test_required_text PASSED  [ 18%]
test_pdf.py::test_title_case PASSED     [ 27%]
test_pdf.py::test_no_links PASSED       [ 36%]
test_pdf.py::test_no_bookmarks PASSED   [ 45%]
test_pdf.py::test_file_size PASSED      [ 54%]
test_pdf.py::test_pages PASSED          [ 63%]
test_pdf.py::test_pdf_version PASSED    [ 72%]
test_pdf.py::test_metadata PASSED       [ 81%]
test_pdf.py::test_embedded_fonts PASSED [ 90%]
test_pdf.py::test_dimensions PASSED     [100%]

Related work

There are many test frameworks and PDF readers that could have been used instead of pytest and pyMuPDF. In the past I have used rspec with pdf/reader which is easy to get started with, but since I am more familiar with Python I opted for that when it came to more advanced tests.

The IEEE Xpress PDF checks or The IEEE LaTeX Analyzer from the IEEE author center do not help us here, since a conference chair can specify other requirements in EDAS that are not checked by these tools.

Discussion

Tests not implemented

There are a few common mistakes that we didn’t create test cases for. The required font sizes is listed by (Shell, 2002), but hard to test for since figures and titles can have wildly different font sizes. Line-spacing is similar to font-size in this regard.

Other common mistakes, such as not referencing a figure in the text is better suited for linting tools such as textidote.

Conclusions

In this post we have implemented a few test cases to detect common mistakes in IEEE conference submission - before the conference PDF checker catches them. I hope that this saves you some frustration, and some time.