paper tips and tricks
1.0.0
Este repositorio contiene una lista de herramientas, mejores prácticas, consejos y otras pautas que consideramos útiles/importantes al escribir artículos científicos. Algunos son una cuestión de estilo (tendemos a seguir las pautas del Manual de estilo de Chicago) y somos conscientes de que otras personas prefieren hacer las cosas de manera diferente, pero los enumeramos de todos modos para tener una guía coherente. ¡Siéntete libre de adaptar, cambiar, ignorar o incluso desafiar todo lo que escribimos!
La composición tipográfica es la composición de un texto mediante la disposición de los tipos, es decir, letras y símbolos. Es principalmente una cuestión de estética, pero una bella tipografía hace que los documentos sean más fáciles y agradables de leer, ayudando al lector a llegar al mensaje.
A continuación enumeramos algunos consejos y herramientas de composición tipográfica que le ayudarán a redactar sus documentos. Algunos consejos son específicos de LaTeX, pero otros se aplican independientemente de lo que esté utilizando.
Al escribir documentos LaTeX, coloque una oración por línea en su archivo fuente. Escribir:
This is my first sentence.
This is the second one.
y no:
This is my first sentence. This is the second one.
La razón principal de esto es el control de fuente y la colaboración: al observar los cambios de una confirmación, es mucho más fácil identificar qué oración se cambió si cada una está en su línea separada. De este modo, tus compañeros de trabajo podrán ver los cambios más fácilmente.
Otro beneficio es que podrá identificar mejor los errores cuando nuestro compilador LaTeX solo le proporcione un número de línea.
Nos referiremos a continuación a dos tipos de capitalización:
Utilice el formato de título para todos los títulos de secciones, subsecciones, etc. Para ayudarle a utilizar mayúsculas en las palabras correctas, existe un sitio web útil: capitalizemytitle.com.
A veces, el nombre de un objeto (como figura, tabla, gráfico o algoritmo) y su número de referencia se dividen en dos líneas. Por ejemplo, el nombre del objeto puede estar en una línea, mientras que el número de referencia aparece en la línea siguiente.
Para asegurarse de que LaTeX mantenga tanto el nombre del objeto como su referencia en la misma línea, puede usar el carácter ~ entre el objeto y la referencia. Al utilizar el carácter de tilde ~ de esta manera, puede evitar saltos de línea incómodos y mantener un formato consistente para los nombres de sus objetos y números de referencia en documentos LaTeX.
Figure~ ref { fig:example } displays that the project ...Para asegurarse de no olvidarse de utilizar el carácter de tilde, puede simplificar el proceso creando comandos personalizados para la automatización. He aquí un ejemplo:
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 }}Una vez definidos estos comandos, en lugar de escribir:
Figure~ ref { fig:example }simplemente escriba:
reffig {fig:example}(ejemplo completo)
booktabs puede ayudarle a producir mesas limpias y atractivas.
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 }
En general, evita utilizar líneas verticales en tus tablas. En cambio, si desea agrupar columnas, hágalo en los encabezados usando cmidrule . También puedes reemplazar líneas horizontales con espaciado, usando addlinespace .
Los encabezados de las columnas deben usar mayúsculas en formato de oración (consulte http://www.chicagomanualofstyle.org/15/ch13/ch13_sec019.html).
Puede encontrar más consejos sobre el formato de tablas aquí: http://www.inf.ethz.ch/personal/markusp/teaching/guides/guide-tables.pdf. Aquí hay un bonito GIF que ilustra algunas de estas reglas:
(ejemplo completo)
Utilice el paquete siunitx para formatear todos los números, monedas, unidades, etc.:
usepackage { siunitx }
% ---
This thing costs SI {123456}{ $ }.
There are num {987654} people in this room, SI {38}{ percent } of which are male.
También puedes usarlo para redondear números:
usepackage { siunitx }
% ---
sisetup {
round-mode = places,
round-precision = 3
} %
You can also round numbers, for example num {1.23456}.
Finalmente, puede ayudarte a alinear mejor los números en una tabla:
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 }
(ejemplo completo)
Al escribir ecuaciones, es útil tener una forma coherente y consistente de escribir variables, vectores, matrices, etc. Ayuda al lector a identificar de qué está hablando y a recordar la semántica de cada símbolo.
Proponemos las siguientes reglas para escribir matemáticas:
$x$ )$mathbold{x}$ )$mathbold{X}$ )$X$ ) El comando mathbold proviene del paquete fixmath y es similar a boldmath o bm , excepto que todos los símbolos están en cursiva, incluso las letras griegas (otros paquetes no ponen en cursiva las letras griegas).
Al agregar índices o exponentes a variables, asegúrese de agregarlos fuera del estilo de la variable, es decir, escriba $mathbold{x}_i$ y no $mathbold{x_i}$ .
Debido a que a menudo nos referimos a variables, sugerimos definir los dos comandos siguientes:
renewcommand { vec }[1]{ mathbold {#1}}
newcommand { mat }[1]{ mathbold {#1}} Luego puede usar $vec{x}$ y $mat{X}$ en su documento. Si decide cambiar la forma en que desea formatear las matrices, simplemente tiene que cambiar el comando mat y actualizará todo el documento.
También sugerimos definir comandos para las variables que más utiliza. Por ejemplo, si usa mucho vec{x} y mat{X} , considere definir estos comandos:
newcommand { vx }{ vec {x}}
newcommand { vX }{ mat {X}} Luego puedes escribir ecuaciones más compactas: $vx^T vy = vZ$ .
Tenga en cuenta que siempre debe diseñar las variables con respecto a su tipo. Por ejemplo, el elemento $i$ésimo de un vector vx es x_i y no vx_i (es un número). De manera similar, si tiene una matriz vX , puede llamar a su i- ésima columna vx_i (es un vector, por lo tanto, en negrita) y una si es su elemento x_{ij} , no vX_i y vX_{ij} .
Utilice (...) para escribir ecuaciones en línea. También puedes usar $...$ , pero es un comando TeX y proporciona mensajes de error más oscuros.
Para escribir ecuaciones centradas en sus propias líneas, no use $$...$$ (es uno de los pecados capitales del uso de LaTeX). Funciona, pero da un espaciado incorrecto. Utilice begin{equation*} o begin{align*} en su lugar.
(ejemplo completo)
Para documentos más extensos, como una tesis de maestría o doctorado, puede resultar útil tener referencias anteriores en la bibliografía, para mostrar dónde se citó una referencia. Para hacerlo, simplemente agregue la opción backref=page al paquete hyperref :
usepackage [ backref=page ]{ hyperref }Puede personalizar la forma en que aparecen las referencias anteriores con los siguientes comandos:
renewcommand *{ backref }[1]{}
renewcommand *{ backrefalt }[4]{{ footnotesize [ %
ifcase #1 Not cited. %
or Cited on page~#2 %
else Cited on pages #2 %
fi %
]}}
Las cifras son un componente importante de cualquier artículo, ya que pueden comunicar los resultados al lector. Debe considerar lo que la información de cada figura le dice al lector y que hay suficiente información para respaldar su mensaje, no más. Por ejemplo, si desea mostrar patrones en puntos 2D (hay dos grupos bien separados), ¿no es necesario poner marcas y valores en los ejes (la escala realmente no importa)? Las figuras no deben ser demasiado complejas. Es mejor tener varias figuras que transmitan uno o dos mensajes (el método A es mejor que B, pero converge más lentamente) que tener una figura grande y desordenada.
Algunas figuras están hechas a mano, por ejemplo, para explicar un sistema o dar una imagen global, mientras que otras se basan en datos, es decir, ilustran algunos datos. Estas figuras basadas en datos deben estar programadas en la medida de lo posible: idealmente, si sus datos cambian, solo debería tener que ejecutar una secuencia de comandos una vez para actualizar su figura, sin ninguna otra intervención (configurar la vista, hacer zoom, guardar/recortar la figura). , etc). De manera similar, si los datos necesarios para generar una figura tardan más de unos segundos en producirse, debe tener un primer script que calcule y guarde los datos, y un segundo script que los trace. De esta forma ahorrarás mucho tiempo a la hora de trabajar en la trama: no tendrás que esperar después de cada pequeño cambio en la figura para ver su efecto.
También recomendamos guardar el comando utilizado para generar una figura en el archivo LaTeX, por ejemplo como un comentario encima de la figura, especialmente si el script requiere argumentos.
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 es posible, todas las figuras deben usar las mismas fuentes para sus etiquetas, ejes, etc. En particular, no debe tener una figura con etiquetas/marcas grandes y otra con etiquetas más pequeñas. Una solución para lograr esto es definir el tamaño de su figura en el script que la genera y no cambiar su escala en su documento (por ejemplo, no cambie el ancho de la figura a textwidth en su documento LaTeX).
Para tener cifras consistentes, recomendamos usar un script auxiliar, similar a nuestro plot_utils.py . Usando este script, simplemente tienes que llamar a la función figure_setup() para definir todos los tamaños, luego crear una figura del tamaño que deseas y guardarla.
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 ) Recomendamos guardar todas las figuras en formato EPS . De esta manera, puede utilizar tanto latex como pdflatex para generar sus documentos y disfrutar de hermosos textos y gráficos vectoriales.
A partir de septiembre de 2015, en Mac OS X y con versiones actualizadas de Python, Matplotlib y TeX Live, hay una pérdida de calidad al imprimir figuras que se guardaron directamente como PDF desde Matplotlib. Se vuelve claro cuando se imprime en papel real; Pruébelo usted mismo. Esta es otra razón para preferir guardar imágenes generadas por Matplotlib en EPS . Si realmente desea conservar solo una versión PDF de la figura, utilice la herramienta de línea de comando epspdf ; el PDF resultante será mejor que el producido directamente por Matplotlib.
Para completar, tenga en cuenta que hay otro backend de Matplotlib, PGF, que produce resultados ligeramente superiores. Sin embargo, a partir de septiembre de 2015, los archivos PDF resultantes pesan el doble que los obtenidos con el backend predeterminado y epspdf .
Matplotlib, incluso cuando utiliza funciones de diseño estrictas, a veces agrega demasiado espacio en blanco en los márgenes. Una ingeniosa herramienta de línea de comandos para recortar un PDF hasta su cuadro delimitador más ajustado pdfcrop .
Si tiene muchos puntos de datos en su gráfico, el archivo EPS resultante puede ser muy grande. Podrías guardar tu figura como un archivo PNG, pero esto daría como resultado textos borrosos. La solución es rasterizar partes de su figura, es decir, decirle matplotlib que los puntos de datos deben representarse como un mapa de bits en el archivo EPS, mientras que el resto está en formato vectorial.
Puede pasar la palabra clave rasterized=True a la mayoría de las funciones de trazado en matplotlib . También puede usar diferentes capas usando zorder y decirle matplotlib que rasterice todas las capas debajo de un zorder determinado usando el método set_rasterization_zorder() del eje. Consulte figure_rasterized_example.py y http://matplotlib.org/examples/misc/rasterization_demo.html para ver ejemplos de rasterización.
