paper tips and tricks
1.0.0
Este repositório contém uma lista de ferramentas, melhores práticas, dicas e outras diretrizes que consideramos úteis/importantes ao escrever artigos científicos. Alguns são uma questão de estilo (tendemos a seguir as diretrizes do Manual de Estilo de Chicago), e sabemos que outras pessoas preferem fazer as coisas de maneira diferente, mas os listamos de qualquer maneira para ter um guia consistente. Sinta-se à vontade para adaptar, alterar, ignorar ou até desafiar tudo o que escrevemos!
A composição tipográfica é a composição do texto por meio da organização dos tipos, ou seja, letras e símbolos. É principalmente uma questão de estética, mas uma tipografia bonita torna os documentos mais fáceis e agradáveis de ler, ajudando o leitor a entender a mensagem.
Listamos abaixo algumas dicas e ferramentas de composição tipográfica para ajudá-lo na hora de redigir seus documentos. Algumas dicas são específicas para o LaTeX, mas outras se aplicam independentemente do que você está usando.
Ao escrever documentos LaTeX, coloque uma frase por linha em seu arquivo fonte. Escrever:
This is my first sentence.
This is the second one.
e não:
This is my first sentence. This is the second one.
A principal razão para isso é o controle de origem e a colaboração: ao observar as alterações de um commit, é muito mais fácil identificar qual frase foi alterada se cada uma estiver em sua linha separada. Assim, seus colegas de trabalho poderão ver as mudanças com mais facilidade.
Outro benefício é que você será capaz de identificar melhor os erros quando receber apenas um número de linha do nosso compilador LaTeX.
Nos referiremos a seguir a dois tipos de capitalização:
Use o formato de título para todos os títulos de seções, subseções, etc. Para ajudá-lo a colocar as palavras certas em maiúscula, existe um site útil: capitalizemytitle.com.
Às vezes, o nome de um objeto (como Figura, Tabela, Gráfico ou Algoritmo) e seu número de referência são divididos em duas linhas. Por exemplo, o nome do objeto pode estar em uma linha, enquanto o número de referência aparece na linha seguinte.
Para garantir que o LaTeX mantenha o nome do objeto e sua referência na mesma linha, você pode usar o caractere ~ entre o objeto e a referência. Ao usar o caractere til ~ dessa forma, você pode evitar quebras de linha estranhas e manter uma formatação consistente para nomes de objetos e números de referência em documentos LaTeX.
Figure~ ref { fig:example } displays that the project ...Para garantir que você não se esqueça de usar o caractere til, você pode simplificar o processo criando comandos personalizados para automação. Aqui está um exemplo:
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 }}Uma vez definidos esses comandos, em vez de escrever:
Figure~ ref { fig:example }basta digitar:
reffig {fig:example}(exemplo completo)
booktabs pode ajudá-lo a produzir tabelas limpas e bonitas.
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 }
Em geral, evite usar linhas verticais em suas tabelas. Em vez disso, se você quiser agrupar colunas, faça isso nos cabeçalhos usando cmidrule . Você também pode substituir linhas horizontais por espaçamento, usando addlinespace .
Os cabeçalhos das colunas devem usar letras maiúsculas no formato de frase (consulte http://www.chicagomanualofstyle.org/15/ch13/ch13_sec019.html).
Você pode encontrar mais conselhos sobre formatação de tabelas aqui: http://www.inf.ethz.ch/personal/markusp/teaching/guides/guide-tables.pdf. Aqui está um belo GIF que ilustra algumas dessas regras:
(exemplo completo)
Use o pacote siunitx para formatar todos os números, moedas, unidades, etc:
usepackage { siunitx }
% ---
This thing costs SI {123456}{ $ }.
There are num {987654} people in this room, SI {38}{ percent } of which are male.
Você também pode usá-lo para arredondar números:
usepackage { siunitx }
% ---
sisetup {
round-mode = places,
round-precision = 3
} %
You can also round numbers, for example num {1.23456}.
Finalmente, pode ajudá-lo a alinhar melhor os números em uma tabela:
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 }
(exemplo completo)
Ao escrever equações, é útil ter uma forma coerente e consistente de escrever variáveis, vetores, matrizes, etc. Isso ajuda o leitor a identificar do que você está falando e a lembrar a semântica de cada símbolo.
Propomos as seguintes regras para escrever matemática:
$x$ )$mathbold{x}$ )$mathbold{X}$ )$X$ ) O comando mathbold vem do pacote fixmath e é semelhante a boldmath ou bm , exceto que todos os símbolos estão em itálico, até mesmo letras gregas (outros pacotes não colocam letras gregas em itálico).
Ao adicionar índices ou expoentes a variáveis, certifique-se de adicioná-los fora do estilo da variável, ou seja, escreva $mathbold{x}_i$ e não $mathbold{x_i}$ .
Como frequentemente nos referimos a variáveis, sugerimos definir os dois comandos a seguir:
renewcommand { vec }[1]{ mathbold {#1}}
newcommand { mat }[1]{ mathbold {#1}} Você pode então usar $vec{x}$ e $mat{X}$ em seu documento. Se você decidir alterar a forma como deseja formatar as matrizes, basta alterar o comando mat e ele atualizará todo o documento.
Sugerimos também definir comandos para as variáveis que você mais utiliza. Por exemplo, se você usa muito vec{x} e mat{X} , considere definir estes comandos:
newcommand { vx }{ vec {x}}
newcommand { vX }{ mat {X}} Você pode então escrever equações mais compactas: $vx^T vy = vZ$ .
Observe que você deve sempre estilizar as variáveis de acordo com seu tipo. Por exemplo, o $i$-ésimo elemento de um vetor vx é x_i e não vx_i (é um número). Da mesma forma, se você tiver uma matriz vX , pode chamar sua i- ésima coluna vx_i (é um vetor, portanto em negrito) e uma se for seu elemento x_{ij} , não vX_i e vX_{ij} .
Use (...) para escrever equações embutidas. Você também pode usar $...$ , mas é um comando TeX e fornece mensagens de erro mais obscuras.
Para escrever equações centradas em suas próprias linhas, não use $$...$$ (é um dos pecados capitais do uso do LaTeX). Funciona, mas dá espaçamento errado. Use begin{equation*} ou begin{align*} .
(exemplo completo)
Para documentos mais longos, como teses de mestrado ou doutorado, pode ser útil ter referências anteriores na bibliografia, para mostrar onde uma referência foi citada. Para fazer isso, basta adicionar a opção backref=page ao pacote hyperref :
usepackage [ backref=page ]{ hyperref }Você pode personalizar a forma como as referências anteriores aparecem com os seguintes comandos:
renewcommand *{ backref }[1]{}
renewcommand *{ backrefalt }[4]{{ footnotesize [ %
ifcase #1 Not cited. %
or Cited on page~#2 %
else Cited on pages #2 %
fi %
]}}
As figuras são um componente importante de qualquer artigo, pois podem comunicar seus resultados ao leitor. Você deve considerar o que as informações de cada figura dizem ao seu leitor e se há informações suficientes para apoiar sua mensagem, e não mais. Por exemplo, se você deseja mostrar padrões em pontos 2d (existem dois clusters bem separados), é desnecessário colocar marcas e valores nos eixos (a escala realmente não importa)? Os números não devem ser muito complexos. É melhor ter várias figuras transmitindo uma ou duas mensagens (o método A é melhor que o B, mas converge mais lentamente) do que ter uma figura grande e confusa.
Algumas figuras são feitas à mão, por exemplo, para explicar um sistema ou dar uma imagem global, enquanto outras são baseadas em dados, ou seja, ilustram alguns dados. Essas figuras baseadas em dados devem ser programadas tanto quanto possível: idealmente, se seus dados mudarem, você só deverá executar um script uma vez para atualizar sua figura, sem qualquer outra intervenção (definir a visualização, aplicar zoom, salvar/cortar a figura , etc). Da mesma forma, se os dados necessários para gerar uma figura levarem mais de segundos para serem produzidos, você deverá ter um primeiro script que calcule e salve os dados, e um segundo script que os represente. Dessa forma, você economizará muito tempo ao trabalhar no enredo: não precisará esperar após cada pequena alteração na figura para ver seu efeito.
Também recomendamos salvar o comando usado para gerar uma figura no arquivo LaTeX, por exemplo, como um comentário acima da figura, especialmente se o script exigir 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 } Se possível, todas as figuras devem usar as mesmas fontes para seus rótulos, eixos, etc. Em particular, você não deve ter uma figura com rótulos/marcas grandes e outra com rótulos menores. Uma solução para conseguir isso é definir o tamanho da sua figura no script que a gera, e não redimensioná-la no seu documento (por exemplo, não altere a largura da figura para textwidth no seu documento LaTeX).
Para obter números consistentes, recomendamos o uso de um script auxiliar, semelhante ao nosso plot_utils.py . Usando este script, basta chamar a função figure_setup() para definir todos os tamanhos, depois criar uma figura do tamanho desejado e salvá-la.
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 salvar todas as figuras no formato EPS . Dessa forma, você pode usar latex e pdflatex para gerar seus documentos e desfrutar de belos gráficos vetoriais e textos.
A partir de setembro de 2015, no Mac OS X e com versões atualizadas de Python, Matplotlib e TeX Live, há perda de qualidade ao imprimir figuras que foram salvas diretamente como PDF do Matplotlib. Torna-se claro quando impresso em papel real; experimente você mesmo. Este é outro motivo para preferir salvar imagens geradas pelo Matplotlib em EPS . Se você realmente deseja manter apenas uma versão em PDF da figura, use a ferramenta de linha de comando epspdf --- o PDF resultante será melhor do que aquele produzido diretamente pelo Matplotlib.
Para completar, observe que há outro back-end do Matplotlib, PGF, que produz resultados ligeiramente superiores. No entanto, a partir de setembro de 2015, os PDFs resultantes são duas vezes mais pesados que aqueles obtidos com o back-end padrão e epspdf .
O Matplotlib, mesmo ao usar recursos de layout restritos, às vezes adiciona muito espaço em branco nas margens. Uma ferramenta de linha de comando bacana para cortar um PDF em sua caixa delimitadora mais estreita pdfcrop .
Se você tiver muitos pontos de dados em seu gráfico, o arquivo EPS resultante poderá ser muito grande. Você poderia salvar sua figura como um arquivo PNG, mas isso resultaria em textos borrados. A solução é rasterizar partes da sua figura, ou seja, dizer matplotlib que os pontos de dados devem ser renderizados como um bitmap no arquivo EPS, enquanto o restante está em formato vetorial.
Você pode passar a palavra-chave rasterized=True para a maioria das funções de plotagem em matplotlib . Você também pode usar camadas diferentes usando o zorder e dizer matplotlib para rasterizar todas as camadas abaixo de um determinado zorder usando o método set_rasterization_zorder() do eixo. Consulte figure_rasterized_example.py e http://matplotlib.org/examples/misc/rasterization_demo.html para exemplos de rasterização.
