paper tips and tricks
1.0.0
Ce référentiel contient une liste d'outils, de bonnes pratiques, de conseils et d'autres lignes directrices que nous avons trouvés utiles/importants lors de la rédaction d'articles scientifiques. Certains sont une question de style (nous avons tendance à suivre les directives du Chicago Manual of Style), et nous sommes bien conscients que d'autres personnes préfèrent faire les choses différemment, mais nous les listons quand même pour avoir un guide cohérent. N'hésitez pas à adapter, modifier, ignorer ou même remettre en question tout ce que nous écrivons !
La composition est la composition d'un texte en arrangeant les types, c'est-à-dire les lettres et les symboles. C'est avant tout une question d'esthétique, mais une belle typographie rend les documents plus faciles et plus agréables à lire, aidant ainsi le lecteur à comprendre le message.
Nous listons ci-dessous quelques conseils et outils de composition pour vous aider lors de la rédaction de vos documents. Certains conseils sont spécifiques à LaTeX, mais d'autres s'appliquent quel que soit ce que vous utilisez.
Lorsque vous rédigez des documents LaTeX, mettez une phrase par ligne dans votre fichier source. Écrire:
This is my first sentence.
This is the second one.
et non :
This is my first sentence. This is the second one.
La principale raison en est le contrôle des sources et la collaboration : lorsque l'on examine les modifications d'un commit, il est beaucoup plus facile d'identifier quelle phrase a été modifiée si elles se trouvent chacune sur une ligne distincte. Vos collègues pourront ainsi constater plus facilement les changements.
Un autre avantage est que vous serez en mesure de mieux identifier les erreurs lorsque notre compilateur LaTeX vous donnera uniquement un numéro de ligne.
Nous évoquerons ci-dessous deux types de capitalisation :
Utilisez le format de titre pour tous les titres de section, sous-section, etc. Afin de vous aider à capitaliser les bons mots, il existe un site Web pratique : capitalizemytitle.com.
Parfois, le nom d'un objet (tel qu'une figure, un tableau, un graphique ou un algorithme) et son numéro de référence sont divisés en deux lignes. Par exemple, le nom de l'objet peut figurer sur une ligne, tandis que le numéro de référence apparaît sur la ligne suivante.
Pour garantir que LaTeX conserve à la fois le nom de l'objet et sa référence sur la même ligne, vous pouvez utiliser le caractère ~ entre l'objet et la référence. En utilisant le caractère tilde ~ de cette manière, vous pouvez éviter les sauts de ligne gênants et maintenir un formatage cohérent pour vos noms d'objet et numéros de référence dans les documents LaTeX.
Figure~ ref { fig:example } displays that the project ...Pour vous assurer de ne pas oublier d'utiliser le caractère tilde, vous pouvez simplifier le processus en créant des commandes personnalisées pour l'automatisation. Voici un exemple :
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 }}Une fois ces commandes définies, au lieu d'écrire :
Figure~ ref { fig:example }tapez simplement :
reffig {fig:example}(exemple complet)
booktabs peut vous aider à produire des tableaux propres et jolis.
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 }
De manière générale, évitez d’utiliser des lignes verticales dans vos tableaux. Au lieu de cela, si vous souhaitez regrouper les colonnes, faites-le dans les en-têtes en utilisant cmidrule . Vous pouvez également remplacer les lignes horizontales par un espacement, en utilisant addlinespace .
Les en-têtes de colonnes doivent utiliser des majuscules au format phrase (voir http://www.chicagomanualofstyle.org/15/ch13/ch13_sec019.html).
Vous pouvez trouver plus de conseils sur le formatage des tableaux ici : http://www.inf.ethz.ch/personal/markusp/teaching/guides/guide-tables.pdf. Voici un joli GIF qui illustre certaines de ces règles :
(exemple complet)
Utilisez le package siunitx pour formater tous les nombres, devises, unités, etc :
usepackage { siunitx }
% ---
This thing costs SI {123456}{ $ }.
There are num {987654} people in this room, SI {38}{ percent } of which are male.
Vous pouvez également l'utiliser pour arrondir des nombres :
usepackage { siunitx }
% ---
sisetup {
round-mode = places,
round-precision = 3
} %
You can also round numbers, for example num {1.23456}.
Enfin, cela peut vous aider à mieux aligner les nombres dans un tableau :
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 }
(exemple complet)
Lors de l'écriture d'équations, il est utile d'avoir une manière cohérente et cohérente d'écrire les variables, les vecteurs, les matrices, etc. Cela aide le lecteur à identifier de quoi vous parlez et à se souvenir de la sémantique de chaque symbole.
Nous proposons les règles suivantes pour écrire des mathématiques :
$x$ )$mathbold{x}$ )$mathbold{X}$ )$X$ ) La commande mathbold vient du package fixmath et est similaire à boldmath ou bm , sauf que tous les symboles sont en italique, même les lettres grecques (les autres packages ne mettent pas les lettres grecques en italique).
Lorsque vous ajoutez des indices ou des exposants à des variables, assurez-vous de les ajouter en dehors du style de la variable, c'est-à-dire écrivez $mathbold{x}_i$ et non $mathbold{x_i}$ .
Parce que nous faisons souvent référence à des variables, nous suggérons de définir les deux commandes suivantes :
renewcommand { vec }[1]{ mathbold {#1}}
newcommand { mat }[1]{ mathbold {#1}} Vous pouvez ensuite utiliser $vec{x}$ et $mat{X}$ dans votre document. Si vous décidez de changer la façon dont vous souhaitez formater les matrices, il vous suffit de modifier la commande mat , et elle mettra à jour tout le document.
Nous vous suggérons également de définir des commandes pour les variables que vous utilisez le plus. Par exemple, si vous utilisez beaucoup vec{x} et mat{X} , pensez à définir ces commandes :
newcommand { vx }{ vec {x}}
newcommand { vX }{ mat {X}} Vous pouvez alors écrire des équations plus compactes : $vx^T vy = vZ$ .
Notez que vous devez toujours styliser les variables en fonction de leur type. Par exemple, le $i$ème élément d'un vecteur vx est x_i et non vx_i (c'est un nombre). De même, si vous avez une matrice vX , vous pouvez appeler sa i ème colonne vx_i (c'est un vecteur, donc en gras) et une si son élément x_{ij} , pas vX_i et vX_{ij} .
Utilisez (...) pour écrire des équations en ligne. Vous pouvez également utiliser $...$ , mais il s'agit d'une commande TeX et donne des messages d'erreur plus obscurs.
Pour écrire des équations centrées sur leurs propres lignes, n'utilisez pas $$...$$ (c'est un des péchés capitaux de l'utilisation de LaTeX). Cela fonctionne, mais donne un mauvais espacement. Utilisez plutôt begin{equation*} ou begin{align*} .
(exemple complet)
Pour les documents plus longs, comme une thèse de maîtrise ou de doctorat, il peut être utile d'avoir des références antérieures dans la bibliographie, pour indiquer où une référence a été citée. Pour ce faire, ajoutez simplement l'option backref=page au package hyperref :
usepackage [ backref=page ]{ hyperref }Vous pouvez personnaliser la façon dont les références arrière apparaissent avec les commandes suivantes :
renewcommand *{ backref }[1]{}
renewcommand *{ backrefalt }[4]{{ footnotesize [ %
ifcase #1 Not cited. %
or Cited on page~#2 %
else Cited on pages #2 %
fi %
]}}
Les chiffres sont un élément important de tout article, car ils peuvent communiquer vos résultats au lecteur. Vous devez considérer ce que les informations sur chaque figure disent à votre lecteur et qu'il y a juste assez d'informations pour étayer votre message, pas plus. Par exemple, si vous souhaitez afficher des motifs en points 2D (il y a deux clusters bien séparés), il est inutile de mettre des ticks et des valeurs sur les axes (l'échelle n'a pas vraiment d'importance) ? Les chiffres ne doivent pas être trop complexes. Il est préférable d'avoir plusieurs figures véhiculant un ou deux messages (la méthode A est meilleure que la méthode B, mais converge plus lentement) que d'avoir une seule grande figure désordonnée.
Certaines figures sont réalisées à la main, par exemple pour expliquer un système ou donner une image globale, tandis que d'autres sont basées sur des données, c'est-à-dire pour illustrer certaines données. Ces figures basées sur les données doivent être autant que possible scriptées : idéalement, si vos données changent, vous ne devriez avoir à exécuter un script qu'une seule fois pour mettre à jour votre figure, sans aucune autre intervention (paramétrage de la vue, zoom, enregistrement/recadrage de la figure). , etc). De même, si les données nécessaires à la génération d'une figure prennent plus de quelques secondes, vous devez disposer d'un premier script qui calcule et enregistre les données, et d'un deuxième script qui les trace. De cette façon, vous gagnerez beaucoup de temps lorsque vous travaillerez sur l'intrigue : vous n'aurez pas à attendre après chaque petite modification de la figure pour voir son effet.
Nous recommandons également de sauvegarder la commande utilisée pour générer une figure dans le fichier LaTeX, par exemple en commentaire au-dessus de la figure, surtout si le script nécessite des arguments.
documentclass { article }
usepackage { graphicx }
begin { document }
% python figure_example.py --save ../../examples/figure/figure.eps
begin { figure }
centering
includegraphics {figure.eps}
caption {Example of a sigmoid function}
end { figure }
end { document } Si possible, toutes les figures doivent utiliser les mêmes polices pour leurs étiquettes, axes, etc. En particulier, vous ne devez pas avoir une figure avec de grandes étiquettes/coches et une autre avec des plus petites. Une solution pour y parvenir est de définir la taille de votre figure dans le script qui la génère, et de ne pas la redimensionner dans votre document (par exemple, ne modifiez pas la largeur de la figure à textwidth dans votre document LaTeX).
Pour avoir des chiffres cohérents, nous vous recommandons d'utiliser un script d'assistance, similaire à notre plot_utils.py . A l'aide de ce script, il vous suffit d'appeler la fonction figure_setup() pour définir toutes les tailles, puis de créer une figure de la taille souhaitée et de la sauvegarder.
import argparse
import matplotlib . pyplot as plt
import numpy as np
import plot_utils as pu
def main ( args ):
x = np . linspace ( - 6 , 6 , 200 )
y = 1 / ( 1 + np . exp ( - x ))
pu . figure_setup ()
fig_size = pu . get_fig_size ( 10 , 5 )
fig = plt . figure ( figsize = fig_size )
ax = fig . add_subplot ( 111 )
ax . plot ( x , y , c = 'b' , lw = pu . plot_lw ())
ax . set_xlabel ( '$x$' )
ax . set_ylabel ( '$ \ sigma(x)$' )
ax . set_axisbelow ( True )
plt . grid ()
plt . tight_layout ()
if args . save :
pu . save_fig ( fig , args . save )
else :
plt . show ()
if __name__ == '__main__' :
parser = argparse . ArgumentParser ()
parser . add_argument ( '-s' , '--save' )
args = parser . parse_args ()
main ( args ) Nous vous recommandons de sauvegarder toutes les figures au format EPS . De cette façon, vous pouvez utiliser à la fois latex et pdflatex pour générer vos documents et profiter de superbes graphiques et textes vectoriels.
Depuis septembre 2015, sur Mac OS X et avec les versions à jour de Python, Matplotlib et TeX Live, il y a une perte de qualité lors de l'impression de figures directement enregistrées au PDF depuis Matplotlib. Cela devient clair lorsqu’il est imprimé sur du vrai papier ; essayez-le par vous-même. C'est une autre raison de préférer enregistrer les images générées par Matplotlib en EPS . Si vous souhaitez vraiment conserver uniquement une version PDF de la figure, utilisez l'outil de ligne de commande epspdf --- le PDF résultant sera meilleur que celui directement produit par Matplotlib.
Pour être complet, notez qu'il existe un autre backend Matplotlib, PGF, qui produit des résultats légèrement supérieurs. Cependant, depuis septembre 2015, les PDF résultants sont deux fois plus lourds que ceux obtenus avec le backend par défaut et epspdf .
Matplotlib, même en utilisant des fonctionnalités de mise en page étroites, ajoute parfois trop d'espace blanc dans les marges. Un astucieux outil de ligne de commande pour recadrer un PDF dans sa zone de délimitation la plus étroite pdfcrop .
Si votre tracé contient de nombreux points de données, le fichier EPS résultant peut être très volumineux. Vous pouvez enregistrer votre figurine au format PNG, mais cela entraînerait des textes flous. La solution est de rastériser certaines parties de votre figure, c'est-à-dire d'indiquer matplotlib que les points de données doivent être rendus sous forme de bitmap dans le fichier EPS, tandis que le reste est au format vectoriel.
Vous pouvez transmettre le mot-clé rasterized=True à la plupart des fonctions de traçage dans matplotlib . Vous pouvez également utiliser différentes couches en utilisant le zorder et dire matplotlib de pixelliser toutes les couches situées en dessous d'un zorder donné en utilisant la méthode set_rasterization_zorder() de l'axe. Voir figure_rasterized_example.py et http://matplotlib.org/examples/misc/rasterization_demo.html pour des exemples de rastérisation.
