O que é BookStan e por que você provavelmente vai começar a usá-lo
BookStan é basicamente um template de projeto para transformar modelos Stan em pacotes R prontos para distribuição. Se você já escreveu um modelo em Stan, provavelmente enfrentou a mesma coisa que eu: juntar um monte de arquivos .stan, um arquivo de descrição R, funções de wrapper, e tentando fazer tudo funcionar juntos sem que o compilador do Stan reclame de caminho errado. O BookStan Resolve isso fornecendo uma estrutura pré-configurada. A ideia principal é simples. Você roda um comando de inicialização, ele cria a árvore de diretórios com tudo que um pacote R precisa, e aí você vai preenchendo com seus modelos. O pacote resultante compila os modelos Stan de forma otimizada usando ocmdstanr, e pode ser instalado, testado, versionado e publicado no CRAN ou em repositórios privados sem dor de cabeça.
Bookstan o que é na prática
Na prática, o BookStan cria uma série de coisas para você automaticamente: o diretório R/ com funções de interface, o src/ para o código C++ gerado pelo Stan, arquivos de teste unitário, configuração do pkgdown, e um arquivo DESCRIPTION já formatado corretamente para um pacote que depende de cmdstanr. Você ganha semanas de configuração manual na primeira vez. O fluxo real funciona assim. Você instala o pacote bookstan via remotes ou devtools, chama a função setup para criar o projeto, e então trabalha dentro dele como qualquer desenvolvedor R normal. Os modelos vão para o diretório stan/, você escreve funções R que chamam esses modelos, e o processo de build cuida da compilação.
Como começar com BookStan passo a passo
A instalação é direta se você já tem um ambiente R configurado com os dependências básicos. O pacote principal é o bookstan, mas você também vai precisar do cmdstanr instalado e funcionando, porque é ele que realmente compila os modelos Stan.
remotes::install_github("stan-dev/bookstan")Depois de instalado, o comando de setup cria o projeto. Algo como:
👉 Clique no botão abaixo para saber mais sobre o assunto!
bookstan::setup("meu_pacote_estatistico")Isso gera uma estrutura completa. O diretório criado contém pastas para modelos, funções R, testes, documentação, e configuração de CI. A partir daí, você entra no diretório e começa a adicionar seus arquivos .stan. Um detalhe importante que muitas pessoas perdem: o BookStan espera que seus modelos fiquem em stan/models/. Arquivos fora dessa pasta podem não ser detectados pelo processo de compilação automática. Isso mudou um pouco com o tempo, então vale verificar a documentação mais recente se estiver usando uma versão mais nova.
Problema real que eu encontrei e como resolvi
Tive um problema específico recentemente ao tentar empacotar um modelo com dados simulados incluidos como exemplo. O BookStan gere automaticamente funções de exemplo que dependem dos modelos compilados, mas o cmdstanr estava compilando os modelos de forma incremental durante o desenvolvimento, e isso criava uma inconsistência entre o que o pacote esperava estar em libs/cmdstanr e o que realmente estava lá quando você rodava check(). A solução que funcionou foi configurar o arquivo .Rbuildignore para excluir o cache de compilação temporária, e adicionar um script de pós-build no DESCRIPTION que força uma recompilação limpa dos modelos antes da distribuição. Também desativei a compilação incremental no ambiente de desenvolvimento usando CMDSTANR_COMPILATION_THREADS=1 e fazendo build manual dos modelos via cmdstan_model() com flag de recompilação forçada. Foi um ajuste de meia hora que economizou horas de debugging durante o check do pacote.
Dicas que ninguém conta sobre BookStan
Primeiro, o BookStan não é uma bala de prata. Ele funciona extremamente bem para modelos Stan puros, mas se você precisa de integrações complexas com outros backends ou funcionalidades avançadas do cmdstanr que ainda não têm suporte no template, vai acabar modificando bastante a estrutura gerada. Isso é normal e esperado. Segundo, cuidado com versões. O BookStan evolui junto com o cmdstanr, e às vezes uma atualização do cmdstanr quebra algo no BookStan que só aparece durante o check do pacote. Mantenha ambos atualizados na mesma linha de versionamento quando possível.
Terceiro, e isso é contra-intuitivo para quem vem do ecossistema R tradicional: o BookStan compila os modelos Stan em C++ durante o build do pacote. Isso significa que o tempo de build pode variar drasticamente dependendo da complexidade dos seus modelos. Modelos simples levam segundos. Modelos com variáveis latentes de alta dimensão e estruturas hierárquicas complexas podem levar de 10 a 30 minutos na primeira compilação. Planeje seu fluxo de desenvolvimento considerando isso, especialmente se for rodar CI/CD.
Quando não usar BookStan
Se o seu objetivo é apenas rodar alguns modelos Stan rapidamente sem a intenção de distribuir o código como pacote, o BookStan adiciona complexidade desnecessária. Use cmdstanr diretamente. Se você precisa de modelos que dependem fortemente de extensões C++ personalizadas fora do padrão do Stan, o BookStan pode limitar suas opções de configuração. E se você está trabalhando com fluxo de trabalho puramente no R sem necessidade de empacotamento, ferramentas como o pacote brms ou mesmo scripts diretos com rstan são mais adequados. O BookStan brilha quando você tem modelos Stan que quer transformar em pacotes reutilizáveis, testáveis e publicáveis. É a ferramenta certa para o cenário certo. Fora disso, outras abordagens podem ser mais eficientes.
