Exemplos

Do download ao gráfico, com o código todo à mostra

Cada exemplo abaixo é completo: copiar, colar e rodar. Os gráficos foram gerados com o próprio código mostrado.

Para jornalismo

O ranking do meu estado

A pergunta mais comum de uma redação: quais cidades daqui estão pior?

library(MAPEmunicipios)

mape_ranking("taxa_homicidios",
             ano = 2019,
             uf = "BA",
             populacao_minima = 50000,
             n = 10)

O populacao_minima não é detalhe técnico. Sem ele, o topo do ranking seria ocupado por municípios de três mil habitantes que tiveram um homicídio no ano — 33 por 100 mil, número que não descreve nada. Com piso de 50 mil, a comparação passa a significar alguma coisa.

Para o país inteiro, em municípios grandes:

Antes de publicar

O número acima vem do SIM, o registro de óbitos do DataSUS, e conta óbitos por agressão do município de residência da vítima. As secretarias estaduais publicam números por município do fato, e os dois raramente coincidem.

Não é que um esteja certo e o outro errado — eles respondem perguntas diferentes. O que não dá é comparar uma série com a outra.

A cidade que quero cobrir, ao longo do tempo

d <- mape_juntar("seguranca", "populacao", "economia",
                 territorio = TRUE)

manaus <- subset(d, id_municipio == mape_resolver_municipio("Manaus"))

with(manaus, plot(ano, sim_obitos_homicidio_i / populacao_residente_i * 1e5,
                  type = "l", lwd = 2,
                  xlab = "", ylab = "homicídios por 100 mil hab."))

Para pesquisa

Montar um painel para regressão

library(MAPEmunicipios)

painel <- mape_juntar("economia", "populacao", "educacao", "saude",
                      territorio = TRUE)

# A chave é única por construção: mape_juntar() teria parado se não fosse.
nrow(painel)
length(unique(paste(painel$id_municipio, painel$ano)))

A junção é full por padrão, então a linha existe se qualquer um dos eixos tiver dado. Para o painel balanceado, use tipo = "inner" — e conte quanto sobrou, porque a interseção de quatro eixos com coberturas diferentes costuma ser menor do que se espera.

Ler o observado, não o painel

Quando a pergunta é sobre a medição e não sobre a série, leia a fonte:

# 5.570 linhas: o retrato de 2015 do AdaptaBrasil, uma por município
risco <- mape_ler("meio_ambiente/adaptabrasil")

# 11.130 linhas: as duas medições censitárias do IVS, sem replicação
ivs <- mape_ler("sociedade/atlas_ivs")

# 55.694 linhas: só os anos de divulgação do IDEB, sem o ano par copiado
ideb <- mape_ler("educacao/ideb")

Isso importa para qualquer coisa que conte observações. Numa regressão com erro padrão agrupado, usar a dimensão em vez da fonte multiplica artificialmente o número de observações do AdaptaBrasil por onze — e os erros padrão saem pequenos demais.

Conferir uma conta em vez de confiar nela

d <- mape_calcular("pib_per_capita", anos = 2021, insumos = TRUE)
head(d)

Com insumos = TRUE, as colunas do numerador e do denominador voltam junto. A base antiga tinha uma coluna de PIB per capita que não era reproduzível: o denominador vinha de uma segunda extração da população, descartada logo depois de dividir. Aqui a conta fica à vista.

Para sociedade civil

Meu município recebe quanto de emenda?

fin <- mape_ler("financas", territorio = TRUE)

meu <- subset(fin, id_municipio == mape_resolver_municipio("Petrolina", uf = "PE"))
meu[, c("ano", "emendas_valor_total_brl2023", "emendas_valor_saude_brl2023")]

A tabela de finanças tem 222 chaves duplicadas, porque a fonte das emendas associa o gasto ao município por nome, sem UF. Se o seu município tem homônimo em outro estado, confira o valor antes de usar. mape_sobre() registra isso.

O saneamento melhorou?

esgoto <- mape_calcular("cobertura_esgoto", uf = "PE", territorio = TRUE)
esgoto <- subset(esgoto, !is.na(cobertura_esgoto))

boxplot(cobertura_esgoto ~ ano, data = esgoto,
        xlab = "", ylab = "% da população urbana com esgoto")

O SNIS é declaratório: município que não responde ao levantamento aparece como vazio, não como zero. Uma queda na cobertura entre dois anos pode ser queda real ou pode ser um município que deixou de responder — e a diferença entre as duas coisas é grande.

Comparar o meu estado com os vizinhos

A mediana municipal por estado, que é o que o gráfico abaixo mostra, é mais honesta que a média: com municípios de 800 a 12 milhões de habitantes, a média descreve a capital.

d <- mape_calcular(c("taxa_homicidios", "pib_per_capita"), anos = 2019,
                   territorio = TRUE)

aggregate(taxa_homicidios ~ sigla_uf, d, median, na.rm = TRUE)

Combinando com mapas

O pacote não traz geometria, para não pesar. Para mapear, use o geobr:

# install.packages("geobr")
library(geobr)
library(ggplot2)

malha <- read_municipality(year = 2020, showProgress = FALSE)
malha$id_municipio <- as.character(malha$code_muni)

d <- mape_calcular("taxa_homicidios", anos = 2019)
mapa <- merge(malha, d, by = "id_municipio", all.x = TRUE)

ggplot(mapa) +
  geom_sf(aes(fill = taxa_homicidios), color = NA) +
  scale_fill_viridis_c(option = "inferno", direction = -1, na.value = "grey92") +
  theme_void()

O geobr devolve code_muni como número. Converter para texto com as.character() antes de juntar não é opcional: sem isso, a junção deixa de casar em todo município cujo código começa com zero.

Onde continuar

Os dados →

O esquema completo, o catálogo e a busca por variável.

Referência →

Todas as funções, com argumentos e valor de retorno.

O ETL →

Como cada número foi produzido, e como atualizá-lo.