Best practice and tips & tricks to write scientific papers in

# Tips and Tricks for Writing Scientific Papers ## Table of contents * [Tips and Tricks for Writing Scientific Papers](#tips-and-tricks-for-writing-scientific-papers) * [Table of contents](#table-of-contents) * [What is this?](#what-is-this) * [Typesetting your paper](#typesetting-your-paper) * [One sentence per line](#one-sentence-per-line) * [Capitalization](#capitalization) * [Keep references whole](#keep-references-whole) * [Tables](#tables) * [Number formatting](#number-formatting) * [Mathematical notation](#mathematical-notation) * [Notation](#notation) * [Define custom commands](#define-custom-commands) * [Use the correct notation for columns et elements](#use-the-correct-notation-for-columns-et-elements) * [Environments](#environments) * [Bibliography](#bibliography) * [Back references](#back-references) * [Creating figures](#creating-figures) * [One script per data\-driven figure](#one-script-per-data-driven-figure) * [Python helper script](#python-helper-script) * [Figures format](#figures-format) * [Rasterize parts of the figure](#rasterize-parts-of-the-figure) * [Useful resources](#useful-resources) ## What is this? This repository contains a list of tools, best practices, tips and other guidelines we found useful/important when writing scientific papers. Some are a matter of style (we tend to follow the guidelines of the Chicago Manual of Style), and we are well aware that other people prefer to do things differently, but we list them anyway to have a consistent guide. Feel free to adapt, change, ignore, or even challenge everything we write! # Typesetting your paper Typesetting is the composition of text by means of arranging the types, i.e., letters and symbols. It is mostly a question of a aesthetics, but beautiful typography makes documents easier and more pleasant to read, helping the reader to get to the message. We list below some typesetting tips and tools to help you when composing your documents. Some tips are specific to LaTeX, but others apply regardless of what you are using. ## One sentence per line When writing LaTeX documents, put one sentence per line in your source file. Write: ``` This is my first sentence. This is the second one. ``` and not: ``` This is my first sentence. This is the second one. ``` The main reason for this is source control and collaboration: when looking at the changes of a commit, it is much easier to identify what sentence was changed if they are each on their separate line. Your coworkers will thus be able to see the changes more easily. Another benefit is that you will be able to better identify errors when only given a line number by our LaTeX compiler. ## Capitalization We will refer below to two types of capitalization: * sentence format : The title of the nice book * title format: The Title of the Nice Book Use title format for all section, subsection, etc. titles. In order to help you capitalize the right words, there's a handy website: [capitalizemytitle.com](https://capitalizemytitle.com). ## Keep references whole Sometimes, the name of an object (such as Figure, Table, Graph, or Algorithm) and its reference number are split into two lines. For instance, the name of the object may be on one line, while the reference number appears on the next line. To ensure that LaTeX keeps both the name of the object and its reference on the same line, you can use the character `~` between the object and the reference. By using the tilde character `~` in this way, you can avoid awkward line breaks and maintain a consistent formatting for your object names and reference numbers in LaTeX documents. ```latex Figure~\ref{fig:example} displays that the project ... ``` To ensure that you don't forget to use the tilde character, you can simplify the process by creating custom commands for automation. Here's an example: ```latex \newcommand{\refalg}[1]{Algorithm~\ref{#1}} \newcommand{\refapp}[1]{Appendix~\ref{#1}} \newcommand{\refchap}[1]{Chapter~\ref{#1}} \newcommand{\refeq}[1]{Equation~\ref{#1}} \newcommand{\reffig}[1]{Figure~\ref{#1}} \newcommand{\refsec}[1]{Section~\ref{#1}} \newcommand{\reftab}[1]{Table~\ref{#1}} ``` Once these commands are defined, instead of writing: ```latex Figure~\ref{fig:example} ``` simply type: ```latex \reffig{fig:example} ``` ## Tables [(complete example)](https://github.com/Wookai/paper-tips-and-tricks/tree/master/examples/booktabs) [booktabs](https://www.ctan.org/pkg/booktabs) can help you produce clean and nice-looking tables. ```latex \usepackage{booktabs} % -- \begin{table} \centering \begin{tabular}{lcc} \toprule & \multicolumn{2}{c}{Data} \\ \cmidrule(lr){2-3} Name & Column 1 & Another column \\ \midrule Some data & 10 & 95 \\ Other data & 30 & 49 \\ \addlinespace Different stuff & 99 & 12 \\ \bottomrule \end{tabular} \caption{My caption.} \label{tab-label} \end{table} ```  In general, avoid using vertical lines in your tables. Instead, if you want to group columns, do it in the headers using `\cmidrule`. You can also replace horizontal lines with spacing, using `\addlinespace`. Column heads should use sentence-format capitalization (see http://www.chicagomanualofstyle.org/15/ch13/ch13_sec019.html). You can find more advice on table formatting here: http://www.inf.ethz.ch/personal/markusp/teaching/guides/guide-tables.pdf. Here is a nice GIF that illustrates some of these rules:  ## Number formatting [(complete example)](https://github.com/Wookai/paper-tips-and-tricks/tree/master/examples/siunitx) Use the [siunitx](https://ctan.org/pkg/siunitx) package to format all numbers, currencies, units, etc: ```latex \usepackage{siunitx} % --- This thing costs \SI{123456}{\$}. There are \num{987654} people in this room, \SI{38}{\percent} of which are male. ```  You can also use it to round numbers: ```latex \usepackage{siunitx} % --- \sisetup{ round-mode = places, round-precision = 3 }% You can also round numbers, for example \num{1.23456}. ```  Finally, it can help you better align numbers in a table: ```latex \usepackage{booktabs} \usepackage{siunitx} %--- \begin{table} \centering \begin{tabular}{lS} \toprule Name & {Value} \\ % headers of S columns have to be in {} \midrule Test & 2.3456 \\ Blah & 34.2345 \\ Foo & -6.7835 \\ Bar & 5642.5 \\ \bottomrule \end{tabular} \caption{Numbers alignment with \texttt{siunitx}.} \end{table} ```  # Mathematical notation [(complete example)](https://github.com/Wookai/paper-tips-and-tricks/tree/master/examples/notation) When writing equations, it is helpful to have a coherent and consistent way of writing variables, vectors, matrices, etc. It helps the reader identifying what you are talking about and remembering the semantics of each symbol. ## Notation We propose the following rules for writing math: * lowercase italic for variables: *x* (`$x$`) * lowercase italic bold for vectors: **_x_** (`$\mathbold{x}$`) * uppercase italic bold for matrices: **_X_** (`$\mathbold{X}$`) * uppercase italic for random variables: *X* (`$X$`) The `\mathbold` command comes from the [`fixmath`](https://www.ctan.org/pkg/fixmath) package and is similar to `\boldmath` or `\bm`, except that all symbols are in italics, even greek letters (other packages do not italicize greek letters). When adding indices or exponents to vari