Um tutorial reprodutível com R e Quarto
Pablo Rogers e Sérgio Murilo Georgeto
Rogers, P., & Georgeto, S. M. [Ano a definir]. Planejamento e avaliação de modelos de análise fatorial confirmatória: um tutorial reprodutível com R e Quarto. [Preprint; repositório e DOI a definir].
Este repositório reúne o artigo-tutorial, os dados e os procedimentos computacionais de uma aplicação de análise fatorial confirmatória (AFC) à WHOQOL-Bref. O percurso articula seleção do modelo, análise de poder, triagem de respostas, estimação MLR/FIML, avaliação global e local, modificações fundamentadas e avaliação da estabilidade entre amostras de calibração e validação por invariância de medida.
O HTML apresenta a narrativa acompanhada de callouts com explicações e código. O PDF preserva a leitura contínua do artigo. A organização dos materiais utiliza o ARTE 2.0 — Article Reproducibility Template & Environment — e a separação de fontes, dados, scripts e resultados do protocolo TIER.
- ✅ Orientações metodológicas para AFC, com justificativa das decisões e aplicação à WHOQOL-Bref.
- ✅ Artigo executável em Quarto, com análises em R e modelos estimados por
lavaan. - ✅ Versões HTML e PDF, com explicações e códigos em callouts no HTML.
- ✅ Resultados persistidos, para reaproveitar simulações e permutações ou recalculá-las de forma controlada.
- ✅ Ambientes configurados com renv e Docker, com versões e limites documentados.
- ✅ Organização baseada no ARTE e no protocolo TIER, separando fontes, entradas, dados derivados e resultados.
O artigo-tutorial tem três objetivos:
- Sistematizar decisões analíticas de AFC fundamentadas na literatura, incluindo planejamento, avaliação e relato dos modelos.
- Demonstrar essas decisões em uma aplicação empírica, com código R integrado às tabelas e figuras.
- Disponibilizar dados, procedimentos e organização de arquivos para examinar, reproduzir e adaptar o percurso analítico.
Principais temas: seleção e fundamentação do modelo de medida; poder analítico e por Monte Carlo; triagem C/IER e dados ausentes; estimação MLR/FIML; ajuste global e local; confiabilidade; modificações fundamentadas; calibração, validação e invariância de medida.
Palavras-chave: Análise Fatorial Confirmatória, Modelagem de Equações Estruturais, Validade da Estrutura Interna, Ciência Aberta, Reprodutibilidade, Quarto e lavaan.
| Recurso | Descrição | Acesso |
|---|---|---|
| 📄 Preprint | Nova versão do artigo | Repositório e DOI a definir |
| 🌐 Artigo | Versão disponibilizada no site | HTML e PDF |
| 🐳 Docker | Imagem pronta para auditoria HTML/PDF | Docker Hub e instruções |
| 📝 Fontes | Resumo, seções, referências e estilo de citação | Article/ |
| 📊 Dados e resultados | Entradas, bases derivadas, simulações e exportações | Data/ e Output/ |
| 🔧 Código compartilhado | Modelos, helpers e persistência | Scripts/ |
O site publicado corresponde à versão disponibilizada remotamente. Um checkout com alterações locais pode conter conteúdo posterior.
cfa-tutorial/
├── index.qmd # Título do resumo e inclusão de Article/00_abstract.qmd
├── _quarto.yml # Ordem das seções, formatos e caminhos do projeto
├── Article/ # Resumo, seções 01–09, referências, BibTeX e CSL
├── Data/
│ ├── InputData/ # Dados de entrada e Metadata/
│ ├── IntermediateData/ # Etapas da triagem e oito resultados RDS
│ └── AnalysisData/ # Base de análise e partição calibração/validação
├── Scripts/
│ ├── DataAppendixScripts/ # Modelos, helpers e mecanismo de persistência
│ ├── ProcessingScripts/ # Pasta reservada; processamento está nos QMDs
│ └── AnalysisScripts/ # Pasta reservada; análises estão nos QMDs
├── Output/
│ ├── Results/ # Tables/ e Figures/ exportadas pelo artigo
│ └── DataAppendixOutput/ # Registro de exclusões em Tables/
├── renv.lock # Versões dos pacotes R
├── renv/ # Ativação e configuração do ambiente R
├── .Rprofile # Ativa renv ao iniciar R na raiz
├── cfa-tutorial.Rproj # Projeto RStudio/Positron
├── docker/ # Dockerfile, Compose e lançadores de auditoria
└── cover.jpg # Capa e favicon
O repositório mantém index.qmd na raiz como página inicial. Os demais documentos estão em Article/. A árvore acima apresenta os arquivos-fonte e as pastas disponibilizados no repositório.
Abra o HTML ou o PDF. O HTML inclui callouts com código e explicações dos procedimentos.
Seguindo a organização do ARTE 2.0, há três caminhos para executar o CFA Tutorial. A leitura do artigo está disponível independentemente deles.
| Nível | Caminho | Preparação |
|---|---|---|
| Mínima | Executar os arquivos em um ambiente R local preparado pelo leitor | Baixar o ZIP ou clonar o projeto e instalar as dependências necessárias |
| Adequada | Restaurar as versões dos pacotes R registradas no projeto | Usar R 4.5.2, Quarto 1.9.37 e renv::restore() |
| Máxima | Auditar o artigo no ambiente da imagem Docker publicada | Instalar e iniciar o Docker e executar audit.bat ou audit.sh |
Os níveis descrevem o controle do ambiente computacional. Nos três caminhos, as etapas demoradas podem reutilizar os oito RDS distribuídos; repetir integralmente as simulações é uma operação separada.
No GitHub, selecione Code → Download ZIP e extraia os arquivos, ou clone o repositório:
git clone https://github.com/phdpablo/cfa-tutorial.git
cd cfa-tutorialAbra cfa-tutorial.Rproj e trabalhe na raiz do projeto. Este caminho exige R, Quarto, os pacotes utilizados nos QMDs e em Scripts/DataAppendixScripts/helpers.R, além de LaTeX para o PDF. O projeto ativa renv por .Rprofile; se a biblioteca ainda não estiver preparada, utilize a restauração descrita no próximo nível. Instalar versões diferentes por conta própria pode alterar os resultados ou impedir a execução.
Instale R 4.5.2 e Quarto 1.9.37. Para trabalhar no RStudio, abra cfa-tutorial.Rproj. Mantenha o diretório de trabalho na raiz do projeto.
Rscript -e "renv::restore(prompt = FALSE)"
quarto --version.Rprofile ativa o ambiente do projeto. renv::restore() instala as versões registradas no lockfile e pode precisar de acesso à internet e ferramentas de compilação, conforme o sistema operacional. Ele não instala a versão do executável R nem o Quarto. Consulte a documentação de restauração do renv.
Para gerar o PDF, prepare uma distribuição LaTeX. Se optar pelo TinyTeX:
quarto install tinytex --no-promptPara uma primeira conferência da configuração, sem executar os chunks:
quarto inspectPara produzir o artigo:
quarto render --to html
quarto render --to pdfPara gerar uma cópia editável do artigo completo em Word, execute quarto render --to docx. O arquivo docs/cfa-tutorial.docx contém a narrativa contínua, sem os blocos didáticos exclusivos do HTML. Antes de fazer inclusões manuais para submissão, salve uma cópia com outro nome fora da pasta docs, pois novas renderizações podem substituir os arquivos gerados.
Ou gere os três formatos com quarto render --to all. Abra o index.html e o cfa-tutorial.pdf gerados no diretório de saída definido em _quarto.yml para conferir a leitura. quarto inspect verifica a configuração, mas não comprova a execução analítica.
O render executa os QMDs na ordem de book.chapters. execute-dir: project e here::here() resolvem os caminhos R a partir da raiz. O pre-render pre_render_cache.R prepara Data/IntermediateData/ e regrava a definição de cache_load_existing(); ele não executa simulações nem carrega automaticamente os RDS.
Alguns callouts contêm chunks executáveis recolhíveis; os exemplos com eval: false são demonstrativos. Não execute uma segunda vez o exemplo de uma rotina apenas por ele estar disponível no callout.
Baixe ou clone o projeto e instale o Docker com suporte a containers Linux. Com o Docker em execução, rode na raiz do repositório:
.\docker\audit.batEm Linux/macOS, use bash docker/audit.sh. Veja as instruções em docker/README.md.
O ambiente CFA Tutorial usa a imagem phdpablo/cfa-tutorial:4.5.2, baseada em rocker/r-ver:4.5.2, com Quarto 1.9.37, dependências de renv.lock e TinyTeX com TeX Live 2026. O serviço audit executa a cópia do artigo incorporada à imagem e exporta HTML, PDF e recursos para docs no computador do usuário.
Os lançadores reutilizam a imagem local ou baixam phdpablo/cfa-tutorial:4.5.2 do Docker Hub quando ela está ausente. Ao encerrar, o container é removido e a imagem permanece no computador. A construção pelo Dockerfile é uma alternativa separada, documentada em docker/README.md. O uso do ARTE 2.0 neste projeto concentra-se na auditoria: o serviço executa a renderização, verifica os produtos e encerra.
Os arquivos locais do artigo não são montados no container. A revisão incorporada à imagem determina o conteúdo auditado; alterações posteriores nos QMDs ou READMEs locais só passam a integrar a imagem após nova construção. docs/audit-summary.txt registra a execução e docs/audit-inputs.sha256 identifica os insumos conferidos.
As versões abaixo são as registradas no checkout; não representam uma recomendação de atualizar para as versões mais recentes.
| Componente | Configuração |
|---|---|
| R principal | 4.5.2, conforme renv.lock e docker/Dockerfile |
| Quarto | 1.9.37, exigido por _quarto.yml e fixado no Dockerfile |
| renv | 1.2.4 |
| lavaan | 0.6-21 |
| semTools | 0.5-7 |
| semPower | 2.1.3 |
| simsem | 0.5-17 |
| dynamic | 1.1.0 |
| LaTeX; TinyTeX pode ser instalado pelo Quarto | |
| Diagramas no PDF | Chrome Headless Shell, instalado no build do Docker principal |
O inventário completo de dependências está em renv.lock. O Docker usa a versão de R do lockfile. A configuração TeX não congela uma versão datada do repositório de pacotes.
O projeto utiliza dois mecanismos independentes:
- Freeze do Quarto:
freeze: autopermite reaproveitar execuções de QMDs em renderizações globais quando as fontes não mudaram. Alterações externas em dados ou scripts podem exigir execução explícita dos QMDs afetados. Renderizar um documento isolado executa seu código, independentemente de freeze. Veja Managing Execution. - Persistência RDS:
cache_or_run()procura primeiro o objeto pelo nome na sessão, depois o RDS emData/IntermediateData/. Se ambos estiverem ausentes, executa a expressão e salva o resultado. Esse mecanismo continua atuando mesmo quando o Quarto executa novamente o documento.
Os oito RDS são distribuídos no repositório e permitem reaproveitar as etapas mais demoradas. Renderizar com eles ainda pode executar triagem, estimações, tabelas e exportações; não equivale a repetir todas as simulações. Consulte o inventário por etapa.
Os parâmetros compartilhados atuais em helpers.R são REP = 10, SEQ = rep(101:400, each = REP), SIM = 1000, N_TARGET = 200 e SEED = 123321. Na seção 4 há 3.000 replicações por condição para N variável e 1.000 por condição para N fixo. As simulações empíricas da seção 7, o 3DFI e a permutação métrica da seção 8 também solicitam 1.000 replicações/permutações. A permutação está configurada com 28 processos; ajuste ncpus à capacidade da máquina antes de recalculá-la.
Para recalcular uma etapa de forma deliberada:
- Identifique no QMD o resultado, os dados e os parâmetros envolvidos. Preserve uma cópia do RDS anterior fora de
Data/IntermediateData/, com registro de sua configuração. - Inicie uma sessão R limpa ou remova da sessão os objetos de cache correspondentes. Retire de
Data/IntermediateData/somente os RDS da etapa a recalcular. Mudar parâmetros não invalida automaticamente arquivos ou objetos existentes. - Execute o QMD correspondente, respeitando as dependências das seções anteriores. Para N variável ou fixo, as duas condições precisam corresponder à mesma configuração.
- Confira o novo resultado e renderize os documentos dependentes. Não trate resultados de um ensaio curto como equivalentes aos da configuração do artigo.
quarto render Article/04_pa.qmd --to html, por exemplo, executa a seção, mas reaproveita seus RDS enquanto estiverem disponíveis. --no-cache não desativa cache_or_run() nem remove os arquivos persistidos. A partição de calibração/validação também é persistida: não a apague ou sorteie novamente para escolher resultados favoráveis.
O processamento parte de 1.546 registros, mantém 1.323 elegíveis após a etapa preliminar e retém 1.243 após os cinco critérios de C/IER. A seção 6 recupera a partição estratificada por ausência nos 24 indicadores: 621 participantes na calibração e 622 na validação. Esses totais descrevem os arquivos atuais; a tabela do artigo é gerada a partir dos dados.
As seções 6–7 estimam e avaliam os modelos originais na calibração. A seção 8 examina o modelo modificado de 21 indicadores na validação e a invariância entre as amostras. A divisão é uma avaliação interna de estabilidade; as decisões históricas sobre itens não devem ser apresentadas como seleção independente de toda a base original. A interpretação e as limitações metodológicas estão no artigo.
Os CSVs do projeto usam ponto e vírgula como delimitador. Para leitura em R, use readr::read_csv2(); exportações numéricas seguem convenções de write_csv2() ou write_excel_csv2(). A documentação de origem e as definições de variáveis estão em Metadata/.
Para adaptar o projeto, comece pelos dados e metadados de entrada, pelas especificações em models.R e pelos parâmetros em helpers.R. Reveja as decisões da triagem, os itens, as condições populacionais, a identificação e a estratégia de validação para a nova pesquisa. Depois recalcule os resultados dependentes e revise a narrativa e os exemplos. A reutilização de um RDS pressupõe correspondência entre dados, modelo e configuração.
Os helpers são documentados junto ao código em helpers.R; os READMEs indicam os papéis dos arquivos, sem duplicar um catálogo de funções. ProcessingScripts/ e AnalysisScripts/ estão reservadas: nesta versão, os próprios QMDs contêm o processamento e as análises.
O Docker permite executar a imagem pronta ou construí-la a partir do checkout selecionado. Os arquivos incorporados à imagem determinam a revisão auditada; alterações posteriores nas fontes locais exigem atualizar a imagem.
Para publicar o artigo no GitHub Pages a partir do branch de fontes, utilize:
quarto publish gh-pagesO repositório deve estar no GitHub, com autenticação e permissão de envio configuradas. Em Settings → Pages, selecione Deploy from a branch, o branch gh-pages e a pasta / (root). Se o branch ainda não existir, a primeira publicação pelo Quarto pode criá-lo; depois confirme essa configuração no GitHub. Execute o comando no branch de fontes, não no próprio gh-pages.
O comando renderiza e envia o conteúdo publicado ao branch gh-pages. A publicação é uma ação explícita, separada do commit dos arquivos-fonte. Consulte as instruções do Quarto para GitHub Pages.
A referência do novo preprint será completada após sua disponibilização. Até lá, os dados bibliográficos confirmados são:
Rogers, P., & Georgeto, S. M. [Ano a definir]. Planejamento e avaliação de modelos de análise fatorial confirmatória: um tutorial reprodutível com R e Quarto. [Preprint; repositório e DOI a definir].
Para identificar a versão computacional utilizada, registre também o commit do repositório e a referência da imagem Docker, quando aplicável. O BibTeX será incluído quando os metadados do novo preprint estiverem definidos.
A infraestrutura deriva do ARTE. Referência: Rogers, P., & Limongi, R. (2025). Open Science in Three Acts: Foundations, Practice, and Implementation — Third Act. BAR — Brazilian Administration Review, 22(3), e250162. DOI.
O projeto é distribuído sob CC BY-NC 4.0. A origem dos dados e a literatura utilizada devem ser reconhecidas ao reutilizar os materiais.