{"id":14980523,"url":"https://github.com/wookai/paper-tips-and-tricks","last_synced_at":"2025-05-14T23:06:59.191Z","repository":{"id":34820928,"uuid":"38808165","full_name":"Wookai/paper-tips-and-tricks","owner":"Wookai","description":"Best practice and tips \u0026 tricks to write scientific papers in LaTeX, with figures generated in Python or Matlab.","archived":false,"fork":false,"pushed_at":"2023-05-17T13:35:30.000Z","size":2023,"stargazers_count":3671,"open_issues_count":4,"forks_count":259,"subscribers_count":66,"default_branch":"master","last_synced_at":"2025-05-14T23:06:41.709Z","etag":null,"topics":["latex","notation","python","research-paper","tips-and-tricks"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Wookai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-07-09T08:31:12.000Z","updated_at":"2025-05-10T14:07:15.000Z","dependencies_parsed_at":"2022-07-10T15:47:05.458Z","dependency_job_id":"39093437-fa6b-4c85-9a22-8ecbcc672b8b","html_url":"https://github.com/Wookai/paper-tips-and-tricks","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wookai%2Fpaper-tips-and-tricks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wookai%2Fpaper-tips-and-tricks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wookai%2Fpaper-tips-and-tricks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wookai%2Fpaper-tips-and-tricks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wookai","download_url":"https://codeload.github.com/Wookai/paper-tips-and-tricks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243362,"owners_count":22038046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["latex","notation","python","research-paper","tips-and-tricks"],"created_at":"2024-09-24T14:01:55.248Z","updated_at":"2025-05-14T23:06:54.180Z","avatar_url":"https://github.com/Wookai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tips and Tricks for Writing Scientific Papers\n\n## Table of contents\n\n  * [Tips and Tricks for Writing Scientific Papers](#tips-and-tricks-for-writing-scientific-papers)\n    * [Table of contents](#table-of-contents)\n    * [What is this?](#what-is-this)\n  * [Typesetting your paper](#typesetting-your-paper)\n    * [One sentence per line](#one-sentence-per-line)\n    * [Capitalization](#capitalization)\n    * [Keep references whole](#keep-references-whole)\n    * [Tables](#tables)\n    * [Number formatting](#number-formatting)\n  * [Mathematical notation](#mathematical-notation)\n    * [Notation](#notation)\n      * [Define custom commands](#define-custom-commands)\n      * [Use the correct notation for columns et elements](#use-the-correct-notation-for-columns-et-elements)\n    * [Environments](#environments)\n  * [Bibliography](#bibliography)\n    * [Back references](#back-references)\n  * [Creating figures](#creating-figures)\n    * [One script per data\\-driven figure](#one-script-per-data-driven-figure)\n    * [Python helper script](#python-helper-script)\n    * [Figures format](#figures-format)\n    * [Rasterize parts of the figure](#rasterize-parts-of-the-figure)\n  * [Useful resources](#useful-resources)\n\n## What is this?\n\nThis repository contains a list of tools, best practices, tips and other guidelines we found useful/important when writing scientific papers.\nSome 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.\nFeel free to adapt, change, ignore, or even challenge everything we write!\n\n# Typesetting your paper\n\nTypesetting is the composition of text by means of arranging the types, i.e., letters and symbols.\nIt 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.\n\nWe list below some typesetting tips and tools to help you when composing your documents.\nSome tips are specific to LaTeX, but others apply regardless of what you are using.\n\n## One sentence per line\n\nWhen writing LaTeX documents, put one sentence per line in your source file.\nWrite:\n```\nThis is my first sentence.\nThis is the second one.\n```\nand not:\n```\nThis is my first sentence. This is the second one.\n```\n\nThe 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.\nYour coworkers will thus be able to see the changes more easily.\n\nAnother benefit is that you will be able to better identify errors when only given a line number by our LaTeX compiler.\n\n## Capitalization\n\nWe will refer below to two types of capitalization:\n\n* sentence format : The title of the nice book\n* title format: The Title of the Nice Book\n\nUse 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).\n\n## Keep references whole\n\nSometimes, the name of an object (such as Figure, Table, Graph, or Algorithm) and its reference number are split into two lines.\nFor instance, the name of the object may be on one line, while the reference number appears on the next line. \n\nTo 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.\nBy 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.\n\n```latex\nFigure~\\ref{fig:example} displays that the project ...\n```\n\nTo 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:\n\n\n```latex\n\\newcommand{\\refalg}[1]{Algorithm~\\ref{#1}}\n\\newcommand{\\refapp}[1]{Appendix~\\ref{#1}}\n\\newcommand{\\refchap}[1]{Chapter~\\ref{#1}}\n\\newcommand{\\refeq}[1]{Equation~\\ref{#1}}\n\\newcommand{\\reffig}[1]{Figure~\\ref{#1}}\n\\newcommand{\\refsec}[1]{Section~\\ref{#1}}\n\\newcommand{\\reftab}[1]{Table~\\ref{#1}}\n```\n\nOnce these commands are defined, instead of writing:\n\n```latex\nFigure~\\ref{fig:example}\n```\n\nsimply type:\n\n```latex\n\\reffig{fig:example}\n```\n\n## Tables\n\n[(complete example)](https://github.com/Wookai/paper-tips-and-tricks/tree/master/examples/booktabs)\n\n[booktabs](https://www.ctan.org/pkg/booktabs) can help you produce clean and nice-looking tables.\n\n```latex\n\\usepackage{booktabs}\n% --\n\\begin{table}\n\t\\centering\n\t\\begin{tabular}{lcc}\n\t\t\\toprule\n\t\t\u0026 \\multicolumn{2}{c}{Data} \\\\ \\cmidrule(lr){2-3}\n\t\tName \u0026 Column 1 \u0026 Another column \\\\\n\t\t\\midrule\n\t\tSome data \u0026 10 \u0026 95 \\\\\n\t\tOther data \u0026 30 \u0026 49 \\\\\n\t\t\\addlinespace\n\t\tDifferent stuff \u0026 99 \u0026 12 \\\\\n\t\t\\bottomrule\n\t\\end{tabular}\n\t\\caption{My caption.}\n\t\\label{tab-label}\n\\end{table}\n```\n\n![Booktabs example](https://github.com/Wookai/paper-tips-and-tricks/raw/master/examples/booktabs/booktabs.png)\n\nIn general, avoid using vertical lines in your tables.\nInstead, if you want to group columns, do it in the headers using `\\cmidrule`.\nYou can also replace horizontal lines with spacing, using `\\addlinespace`.\n\nColumn heads should use sentence-format capitalization (see http://www.chicagomanualofstyle.org/15/ch13/ch13_sec019.html).\n\nYou can find more advice on table formatting here: http://www.inf.ethz.ch/personal/markusp/teaching/guides/guide-tables.pdf.\nHere is a nice GIF that illustrates some of these rules:\n\n![Better table formatting](http://darkhorseanalytics.com/blog/wp-content/uploads/2014/03/ClearOffTheTableMd.gif)\n\n## Number formatting\n\n[(complete example)](https://github.com/Wookai/paper-tips-and-tricks/tree/master/examples/siunitx)\n\nUse the [siunitx](https://ctan.org/pkg/siunitx) package to format all numbers, currencies, units, etc:\n```latex\n\\usepackage{siunitx}\n% ---\nThis thing costs \\SI{123456}{\\$}.\nThere are \\num{987654} people in this room, \\SI{38}{\\percent} of which are male.\n```\n\n![Siunitx formatting](https://github.com/Wookai/paper-tips-and-tricks/raw/master/examples/siunitx/siunitx-formatting.png)\n\nYou can also use it to round numbers:\n```latex\n\\usepackage{siunitx}\n% ---\n\\sisetup{\n\tround-mode = places,\n\tround-precision = 3\n}%\nYou can also round numbers, for example \\num{1.23456}.\n```\n![Siunitx formatting](https://github.com/Wookai/paper-tips-and-tricks/raw/master/examples/siunitx/siunitx-rounding.png)\n\nFinally, it can help you better align numbers in a table:\n```latex\n\\usepackage{booktabs}\n\\usepackage{siunitx}\n%---\n\\begin{table}\n\t\\centering\n\t\\begin{tabular}{lS}\n\t\t\\toprule\n\t\tName \u0026 {Value} \\\\ % headers of S columns have to be in {}\n\t\t\\midrule\n\t\tTest \u0026 2.3456 \\\\\n\t\tBlah \u0026 34.2345 \\\\\n\t\tFoo \u0026 -6.7835 \\\\\n\t\tBar \u0026 5642.5 \\\\\n\t\t\\bottomrule\n\t\\end{tabular}\n\t\\caption{Numbers alignment with \\texttt{siunitx}.}\n\\end{table}\n```\n![Siunitx formatting](https://github.com/Wookai/paper-tips-and-tricks/raw/master/examples/siunitx/siunitx-table.png)\n\n# Mathematical notation\n\n[(complete example)](https://github.com/Wookai/paper-tips-and-tricks/tree/master/examples/notation)\n\nWhen writing equations, it is helpful to have a coherent and consistent way of writing variables, vectors, matrices, etc.\nIt helps the reader identifying what you are talking about and remembering the semantics of each symbol.\n\n## Notation\n\nWe propose the following rules for writing math:\n\n * lowercase italic for variables: *x* (`$x$`)\n * lowercase italic bold for vectors: **_x_** (`$\\mathbold{x}$`)\n * uppercase italic bold for matrices: **_X_** (`$\\mathbold{X}$`)\n * uppercase italic for random variables: *X* (`$X$`)\n\nThe `\\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).\n\nWhen adding indices or exponents to variables, make sure that you add them outside of the styling of the variable, i.e., write `$\\mathbold{x}_i$` and not `$\\mathbold{x_i}$`.\n\n### Define custom commands\n\nBecause we often refer to variables, we suggest defining the following two commands:\n\n```latex\n\\renewcommand{\\vec}[1]{\\mathbold{#1}}\n\\newcommand{\\mat}[1]{\\mathbold{#1}}\n```\n\nYou can then use `$\\vec{x}$` and `$\\mat{X}$` in your document.\nIf you decide to change the way you want to format matrices, you simply have to change the `\\mat` command, and it will update the whole document.\n\nWe also suggest defining commands for the variables you use the most.\nFor example, if you use `\\vec{x}` and `\\mat{X}` a lot, consider defining these commands:\n\n```latex\n\\newcommand{\\vx}{\\vec{x}}\n\\newcommand{\\vX}{\\mat{X}}\n```\n\nYou can then write more compact equations: `$\\vx^T \\vy = \\vZ$`.\n\n### Use the correct notation for columns et elements\n\nNote that you should always style the variables with respect to their type.\nFor example, the $i$th element of a vector `\\vx` is `x_i` and not `\\vx_i` (it is a number).\nSimilarly, if you have a matrix `\\vX`, can call its *i*th column `\\vx_i` (it is a vector, thus in bold) and one if its element `x_{ij}`, not `\\vX_i` and `\\vX_{ij}`.\n\n## Environments\n\nUse `\\(...\\)` to write inline equations.\nYou can also use `$...$`, but it is a TeX command and gives more obscure error messages.\n\nTo write centered equations on their own lines, do not use `$$...$$` (it is one of the [deadly sins of LaTeX use](http://ctan.math.utah.edu/ctan/tex-archive/info/l2tabu/english/l2tabuen.pdf)).\nIt works, but gives wrong spacing.\nUse `\\begin{equation*}` or `\\begin{align*}` instead.\n\n# Bibliography\n\n## Back references\n\n[(complete example)](https://github.com/Wookai/paper-tips-and-tricks/tree/master/examples/backref)\n\nFor longer documents, such as a master or PhD thesis, it can be useful to have back references in the bibliography, to show where a reference was cited.\nTo do so, simply add the option `backref=page` to the `hyperref` package:\n\n```latex\n\\usepackage[backref=page]{hyperref}\n```\n\nYou can customize the way the back references appear with the following commands:\n\n```latex\n\\renewcommand*{\\backref}[1]{}\n\\renewcommand*{\\backrefalt}[4]{{\\footnotesize [%\n    \\ifcase #1 Not cited.%\n\t\\or Cited on page~#2%\n\t\\else Cited on pages #2%\n\t\\fi%\n]}}\n```\n\n![Backref custom appearance](https://github.com/Wookai/paper-tips-and-tricks/raw/master/examples/backref/backref.png)\n\n# Creating figures\n\nFigures are an important component to any paper, as they can communicate your results to the reader.\nYou should consider what the information on each figure tells your reader, and that there is just enough information to support your message, not more.\nFor example, if you want to show patterns in 2d points (there are two clusters well separated), it is unnecessary to put ticks and values on the axes (the scale does not really matter)?\nFigures should not be too complex. It is better to have several figures conveying one or two messages, (method A is better than B, but converges slower) than having one big messy figure.\n\n## One script per data-driven figure\n\nSome figures are hand-made, e.g., to explain a system or give a global picture, whereas others are data-driven, i.e., illustrate some data.\nThese data-driven figures should be scripted as much as possible: ideally, if your data changes, you should only have to run a script once to update your figure, without any other intervention (setting the view, zooming, saving/cropping the figure, etc).\nSimilarly, if the data required to generate a figure takes more than seconds to be produced, you should have a first script that computes and saves the data, and a second script that plots it.\nThis way, you will save a lot of time when working on the plot: you won't have to wait after each small change to the figure to see its effect.\n\nWe also recommend to save the command used to generate a figure in the LaTeX file, for example as a comment above the figure, especially if the script requires arguments.\n\n```latex\n\\documentclass{article}\n\n\\usepackage{graphicx}\n\n\\begin{document}\n\n% python figure_example.py --save ../../examples/figure/figure.eps\n\\begin{figure}\n\t\\centering\n\t\\includegraphics{figure.eps}\n\t\\caption{Example of a sigmoid function}\n\\end{figure}\n\n\\end{document}\n```\n\n## Python helper script\n\nIf possible, all figures should use the same fonts for their labels, axes, etc.\nIn particular, you should not have one figure with big labels/ticks, and another with smaller ones.\nOne solution to achieve this is to define the size of your figure in the script that generates it, and not rescale it in your document (e.g., do not change set the width of the figure to `\\textwidth` in your LaTeX document).\n\nTo have consistent figures, we recommend using a helper script, similar to our [`plot_utils.py`](https://github.com/Wookai/paper-tips-and-tricks/blob/master/src/python/plot_utils.py).\nUsing this script, you simply have to call the `figure_setup()` function to define all the sizes, then create a figure of the size you want, and save it.\n\n```python\nimport argparse\nimport matplotlib.pyplot as plt\nimport numpy as np\nimport plot_utils as pu\n\n\ndef main(args):\n    x = np.linspace(-6, 6, 200)\n    y = 1/(1 + np.exp(-x))\n\n    pu.figure_setup()\n\n    fig_size = pu.get_fig_size(10, 5)\n    fig = plt.figure(figsize=fig_size)\n    ax = fig.add_subplot(111)\n\n    ax.plot(x, y, c='b', lw=pu.plot_lw())\n\n    ax.set_xlabel('$x$')\n    ax.set_ylabel('$\\\\sigma(x)$')\n\n    ax.set_axisbelow(True)\n\n    plt.grid()\n    plt.tight_layout()\n\n    if args.save:\n        pu.save_fig(fig, args.save)\n    else:\n        plt.show()\n\n\nif __name__ == '__main__':\n    parser = argparse.ArgumentParser()\n\n    parser.add_argument('-s', '--save')\n\n    args = parser.parse_args()\n    main(args)\n```\n\n## Figures format\n\nWe recommend saving all figures in the `EPS` format.\nThis way, you can use both `latex` and `pdflatex` to generate your documents, and enjoy beautiful vector graphics and texts.\n\nAs of September 2015, on Mac OS X and with up-to-date versions of Python, Matplotlib and TeX Live, there is a loss of quality when printing figures that were directly saved as `PDF` from Matplotlib.\nIt becomes clearly when printed on real paper; try it out for yourself.\nThis is another reason to prefer saving Matplotlib-generated pictures in `EPS`.\nIf you really want to keep only a PDF version of the figure, use the `epspdf` command line tool---the resulting PDF will be better than that directly produced by Matplotlib.\n\nFor completeness, note that there is another Matplotlib backend, [PGF](http://matplotlib.org/users/pgf.html), that produces slightly superior results.\nHowever, as of September 2015, the resulting PDFs are twice as heavy as those obtained with the default backend and `epspdf`.\n\nMatplotlib, even when using [tight layout features](http://matplotlib.org/users/tight_layout_guide.html), adds at times too much white space in the margins.\nA nifty command-line tool to crop a PDF to its tightest bounding box `pdfcrop`.\n\n## Rasterize parts of the figure\n\nIf you have many data points in your plot, the resulting EPS file might be very big.\nYou could save your figure as a PNG file, but this would result in blurry texts.\nThe solution is to rasterize parts of your figure, i.e., to tell `matplotlib` that the data points have to be rendered as a bitmap in the EPS file, while the rest is in vector format.\n\nYou can pass the `rasterized=True` keyword to most plotting fuctions in `matplotlib`.\nYou can also use different layers using the `zorder` and tell `matplotlib` to rasterize all the layers below a given `zorder` using the `set_rasterization_zorder()` method of the axis.\nSee [figure_rasterized_example.py](https://github.com/Wookai/paper-tips-and-tricks/blob/master/src/python/figure_rasterized_example.py) and http://matplotlib.org/examples/misc/rasterization_demo.html for examples of rasterization.\n\n# Useful resources\n\n* Automatically capitalize your title: https://capitalizemytitle.com\n* Chicago Manual of Style: http://www.chicagomanualofstyle.org\n* Command-line check of weasel words, passive, etc: https://github.com/devd/Academic-Writing-Check\n* An essential guide to LaTeX 2e usage: http://ctan.math.utah.edu/ctan/tex-archive/info/l2tabu/english/l2tabuen.pdf\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwookai%2Fpaper-tips-and-tricks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwookai%2Fpaper-tips-and-tricks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwookai%2Fpaper-tips-and-tricks/lists"}