Relatórios e textos técnicos usando Pweave

Todos os textos do blog são gerados usando uma ferramenta chamada pweave, que permite escrever textos alternando markdown (ou HTML, Latex e reST) e código em Python. Apesar de ser parecido com o Jupyter Notebook, o foco do Pweave é na criação de relatórios e não na execução de código ao mesmo tempo que o texto é editado. Quando um documento é compilado pelo Pweave seu código é executado e um documento de saída é criado com os resultados. Isso facilita muito a edição dos textos, pois podemos usar nosso editor favorito ao invés da interface web do Jupyter (ela não me agrada, mas isto é bem pessoal...).

A instalação do Pweave pode ser feita via conda

conda config --add channels mpastell
conda install pweave

ou fazendo download do código a partir do PyPI. A página inicial do Pweave cite um problema com a instalaçõa via pip e Python 3. Não sei se este problema ainda existe, então pode valer a pena investigar.

Pweave pode ser utilizado de duas maneiras: convertendo um texto em markdown com código Python (usando o comando pweave) ou convertendo um script Python com comentários contendo texto em markdown (usando o comando pypublish). Ambos suportam as praticamente as mesmas funcionalidades, mas dependendo do uso um pode ser mais conveniente que o outro. Eu prefiro o primeiro modo para escrever os textos do blog.

Opções de entrada

Documentos são compostos por dois tipos de trechos (chunks): documentação e código. Trechos de documentação não são processados pelo Pweave e são copiados diretamente para a saída. Trechos de código (code chunks) são executados pelo Pweave e sua saída é colada no documento de resultado. É possível adicionar opções que controlam como a saída é processada. As que mais uso são:

• fig=True: cola figuras do matplotlib no documento;
• caption='': legenda de figuras;
• source='': carregar o código deste chunk de um arquivo;
• evaluate=False: somente mostrar o código, sem avaliar;
• engine='python'|'shell': executar código em Python ou comandos no terminal.

Todas as opções de configuração de code chunks podem ser consultadas aqui.

Opções de saída

A transformação dos trechos de código no documento de saída depende do formato utilizado. Veja abaixo uma lista dos formatos mais comuns:

• markdown: Produz texto em markdown na saída (em formato pandoc);
• md2html: Produz documento HTML a partir de uma entrada em markdown (usando o módulo markdown);
• pandoc2html: Markdown para HTML usando pandoc;
• pandoc2latex Markdown para Latex usando pandoc;
• rest: Documento em Restructured Text.

Mais formatos de saída em Latex podem ser vistos na documentação oficial). Também são suportados outros formatos mais obscuros.

Um ponto importante é que os formatos que exportam HTML suportam equações escritas no formato Latex usando MathJax. Logo, é possível criar textos bastante técnicos e exportar diretamente para HTML (além de Latex,é claro). Um exemplo é o texto que fiz sobre Regressão Logística.

Usando Pypublish

O comando pypublish recebe um arquivo em Python como entrada e devolve um documento formatado. Toda linha de comentário começando com #' é incluída como markdown no documento formatado. O restante do código é executado. Opções para a visualização do código podem ser definidas usando #+. Veja abaixo um exemplo de script que pode ser publicado usando pypublish.

#' % título
#'% author
#'% data

#'este texto é um exemplo em markdown para pweave.

print('hello!')
var = 7

#' O valor de var é <%= var %>!.

#' Abaixo um gráfico (com legenda!). O código usado para gerar o
gráfico não aparece no resultado final.

#+ caption='Gráfico com legenda.',echo=False
import numpy as np
import matplotlib.pyplot as plt
plt.plot(np.random.rand(10), '-')
plt.show()

#' E o texto acaba aqui.

O comando para publicar o script é

pypublish -f (html ou pdf) arquivo.py

Para saída em pdf é necessário ter instalado pandoc e pdflatex.

Usando pweave

O comando pweave recebe um arquivo texto com trechos em Python e o converte para um documento processado contendo os trechos de código e seu resultado. Figuras são embutidas direto na página. O código incluido nos code chunks é executado na mesma seção (ou seja, tudo que foi escrito em um trecho continua valendo nos próximos).

% título
% author
% data

este texto é um exemplo em markdown para pweave.

<<>>=
print('hello!')
var = 7
@

O valor de var é <%= var %>!.

Abaixo um gráfico (com legenda!). O código usado para gerar o gráfico
não aparece no resultado final.

<<caption='Gráfico com legenda.',echo=False>>=
import numpy as np
import matplotlib.pyplot as plt
plt.plot(np.random.rand(10), '-')
plt.show()
@

E o texto acaba aqui.

O comando usado para processar o arquivo acima é:

pweave -f (formato incluso na lista acima) arquivo

Lembre-se de que o arquivo de entrada deverá ser compatível com o formato escolhido. Um outro exemplo pode ser este texto mesmo, que foi compilado usando Pweave. Seu código fonte pode ser visto aqui.

---

O resultado gerado pelos exemplos acima pode ser visto aqui. Apesar de ambos comandos gerarem a mesma saída eles tem usos diferentes. Quando desejamos fazer um texto que contém exemplos e gráficos gerados usando Python é melhor usar o comando pweave. Por outro lado, se temos um código já pronto que precisa ser usado em outros scripts e queremos documentá-lo sem alterar sua funcionalidade podemos usar o pypublish.

Espero que este texto tenha sido útil. Tenho visto o Pweave como uma excelente alternativa ao Jupyter Notebook para a criação de textos técnicos, com a grande vantagem de que posso usar meu editor de texto favorito ao invés da interface Web do Jupyter. Qualquer dúvida ou comentário é só comentar. Se gostou, compartilhe e ajude o blog a ficar mais conhecido ;)