Introdução ao datacaged

Visão Geral

O datacaged simplifica o acesso aos microdados do CAGED (Cadastro Geral de Empregados e Desempregados) diretamente do HuggingFace do Ministério do Trabalho e Emprego (MTE), carregando os dados em um banco DuckDB local para análise eficiente.

Ele suporta três séries:

Período	Série	Tabela no banco
Jan/2020 – hoje	Novo CAGED	`caged_mov`, `caged_for`, `caged_exc`
Jan/1992 – Dez/2019	CAGED antigo	`caged_antigo`
Jan/1992 – Dez/2019	CAGED Ajustes	`caged_ajustes`

Instalação

# Via remotes
remotes::install_github("gecomt/datacaged")

Compatibilidade entre plataformas

O datacaged é compatível com Windows, macOS e Linux sem configuração adicional para o Novo CAGED (2020+).

Recurso	Windows	macOS	Linux
Download (HTTPS)	OK	OK	OK
Downloads paralelos	OK	OK	OK
Novo CAGED (2020+)	OK	OK	OK
CAGED antigo (pré-2020, PPMd)	(!) requer 7-Zip	(!) requer 7-Zip	(!) requer 7-Zip

O CAGED antigo usa compressão PPMd. Se precisar desses dados, instale o 7-Zip:

Windows: baixe o instalador e instale normalmente
macOS: brew install 7-zip
Linux: sudo apt install 7zip ou sudo dnf install 7zip

O Novo CAGED (2020+) usa LZMA, suportado nativamente pelo pacote archive em todas as plataformas.

Downloads paralelos

Por padrão, o pacote baixa 3 arquivos simultaneamente (MOV, FOR e EXC de cada mês), o que resulta em aproximadamente 3× mais velocidade em relação ao modo sequencial.

# Controlar o número de workers
caged_download(years = 2023, months = 1:3, workers = 3)  # padrão

# Configurar globalmente para toda a sessão
options(datacaged.workers = 4)

# Modo sequencial (útil para conexões instáveis)
caged_download(years = 2023, months = 1, workers = 1)

Uso Básico: Pipeline Completo

A função caged_load() faz tudo em um só comando: baixa os .7z do HuggingFace, extrai, normaliza e grava no DuckDB.

library(datacaged)

# Baixa Novo CAGED de Jan–Dez/2023 para SP e RJ
# Novo CAGED: arquivo nacional, `states` não filtra
caged_load(
  years    = 2023,
  months   = seq_len(12L),
  db_path = "caged.duckdb"
)

O progresso é exibido no terminal com barra de andamento e resumo final.

Consulta dos Dados

Após popular o banco, conecte e consulte com dplyr ou SQL puro:

library(dplyr)

con <- caged_connect("caged.duckdb")

# Saldo de empregos por mês em 2023
saldo_mensal <- tbl(con, "caged_mov") |>
  group_by(competenciamov) |>
  summarise(saldo = sum(saldomovimentacao, na.rm = TRUE)) |>
  arrange(competenciamov) |>
  collect()

saldo_mensal

# Ou com SQL direto
DBI::dbGetQuery(con, "
  SELECT
    competenciamov,
    uf,
    SUM(saldomovimentacao) AS saldo,
    AVG(salario)           AS salario_medio,
    COUNT(*)               AS movimentacoes
  FROM caged_mov
  WHERE uf = 35          -- Sao Paulo
  GROUP BY competenciamov, uf
  ORDER BY competenciamov
")

Sempre feche a conexão ao terminar:

DBI::dbDisconnect(con, shutdown = TRUE)

Funções Granulares

Para mais controle, use as funções individualmente:

1. Só baixar os arquivos

# Baixa e salva em cache local (~/.local/share/R/datacaged por padrão)
manifest <- caged_download(
  years    = 2023,
  months   = c(1L, 2L, 3L),
  destdir = "~/meus_dados/caged_cache"
)

# manifest é um data.frame com status de cada arquivo
dplyr::count(manifest, status)

2. Parsear arquivos manualmente

# Um arquivo por vez
df <- caged_parse("~/meus_dados/caged_cache/caged_mov/2023/CAGEDMOV202301.7z")
glimpse(df)

# Vários de uma vez
arquivos <- list.files(
  "~/meus_dados/caged_cache/NOVO_CAGED/2023",
  pattern    = "CAGEDMOV",
  full.names = TRUE
)
df_todos <- caged_parse_batch(arquivos)

3. Gravar no banco

caged_to_duckdb(df_todos, db_path = "caged.duckdb")

Ver o que está no banco

caged_info("caged.duckdb")
#> ── caged.duckdb ────────────────────────────────────────
#> Tamanho do arquivo: 142.3 MB
#> ── Tabelas ──────────────────────────────────────────────
#> * "caged_mov"   Registros: 3,665,155
#> * "caged_for"      Registros:    91,098
#> * "caged_exc"       Registros:     7,900
#>   Registros   : 4.823.901
#>   Competências: 202301 – 202312

Exemplo: Série Histórica com CAGED Antigo

# Baixa CAGED antigo para Nordeste (2015–2019)
nordeste <- c("MA", "PI", "CE", "RN", "PB", "PE", "AL", "SE", "BA")

caged_load(
  years    = 2015:2019,
  db_path = "caged_historico.duckdb"
)

con <- caged_connect("caged_historico.duckdb")

# Evolução anual do saldo formal no Nordeste
tbl(con, "caged_antigo") |>
  mutate(ano = as.integer(substr(as.character(competencia), 1, 4))) |>
  group_by(ano, uf) |>
  summarise(saldo = sum(saldomovimentacao, na.rm = TRUE)) |>
  collect() |>
  tidyr::pivot_wider(names_from = uf, values_from = saldo)

DBI::dbDisconnect(con, shutdown = TRUE)

CAGED Ajustes

O CAGED Ajustes contém correções retroativas do CAGED antigo (até 2019). Use caged_adjustments_load() para baixar e gravar na tabela caged_ajustes.

# Baixar ajustes de 2019
caged_adjustments_load(years = 2019, months = seq_len(12L), db_path = "caged.duckdb")

# Listar o que está disponível no HuggingFace
caged_hf_files(type = "ajustes")

# Comparar saldo original vs ajustado
con <- caged_connect("caged.duckdb")

antigo  <- dplyr::tbl(con, "caged_antigo")  |>
  dplyr::group_by(competencia) |>
  dplyr::summarise(saldo_original = sum(saldomovimentacao, na.rm = TRUE))

ajustes <- dplyr::tbl(con, "caged_ajustes") |>
  dplyr::group_by(competencia) |>
  dplyr::summarise(saldo_ajuste = sum(saldomovimentacao, na.rm = TRUE))

dplyr::full_join(antigo, ajustes, by = "competencia") |>
  dplyr::mutate(saldo_final = saldo_original + saldo_ajuste) |>
  dplyr::collect()

DBI::dbDisconnect(con, shutdown = TRUE)

Dicas de Performance

DuckDB é colunar: prefira select() antes de collect() para trazer apenas as colunas necessárias.
Re-runs são seguros: caged_load() pula competências já no banco por padrão. Use overwrite_competencies = TRUE para regravar.
Cache de .7z: os arquivos baixados ficam em ~/.local/share/R/datacaged. Você pode reutilizá-los sem nova conexão ao HuggingFace.
Memória: o pipeline processa uma competência por vez para evitar consumo excessivo de RAM com grandes períodos.

Utilitários

# Verificar se o HuggingFace está online antes de baixar
caged_status()

# Listar competências disponíveis no HuggingFace
caged_hf_files()                     # Novo CAGED (últimos 12 meses)
caged_hf_files(type = "antigo")      # CAGED antigo
caged_hf_files(type = "ajustes")     # CAGED Ajustes

# Atualização incremental — baixa apenas o que ainda não está no banco
caged_update(db_path = "caged.duckdb")
caged_update(db_path = "caged.duckdb", series = c("novo", "antigo"))

# Exportar tabelas para Parquet (nativo DuckDB, muito rápido)
caged_to_parquet("caged.duckdb", output_dir = "~/exports")
caged_to_parquet("caged.duckdb", output_dir = "~/exports",
                 tables = "caged_mov", partition_by = "uf")

Variáveis principais

Coluna	Descrição
`competenciamov`	Competência no Novo CAGED, formato `AAAAMM` (ex: `202301`)
`competencia`	Competência no CAGED antigo e Ajustes, formato `AAAAMM`
`uf`	Código IBGE da UF (ex: `35` = SP)
`municipio`	Código IBGE do município
`saldomovimentacao`	`+1` admissão, `-1` desligamento
`salario`	Salário contratual em R$
`sexo`	`1` masculino, `3` feminino
`idade`	Idade em anos
`escolaridade`	Código de grau de instrução (1–9)
`racacor`	Código de raça/cor (1–5)
`tipomovimentacao`	Código do motivo da movimentação
`secao`	Seção da CNAE 2.0 (Novo CAGED)
`fonte_tipo`	`MOV`, `FOR`, `EXC`, `ANTIGO` ou `AJUSTES`