Posso usar estes dados?

Versão

pt-synthpop 1.0.3, datada de 5 de outubro de 2026 (publicada no GitHub a 6 de outubro de 2026)

Ano de referência

2021: gerada a partir dos Censos 2021 do INE.

Modelo

Motor v10, uma única execução. sha256 062e2ad784886b7287536233f853db151c57615d2b1a952fb2e12368581e76d3

Código

Commit 4bf0819 do código de empacotamento; o repositório ainda não é público.

Versões anteriores

A 1.0.3 substituiu três versões datadas de 5 de outubro (a 1.0.2 nunca chegou ao GitHub); a população gerada é a mesma em todas.

O que mudou entre as versões

A versão 1.0.3 substituiu as versões 1.0.0, 1.0.1 e 1.0.2, todas de 5 de outubro de 2026. A 1.0.0 aplicava às respostas do site limiares de lançamento que escondiam cerca de metade das respostas das freguesias; a 1.0.1 retirou-os, e cada freguesia passou a responder com os seus próprios números; a 1.0.2 passou as perguntas sobre agregados para os agregados privados e corrigiu a apresentação; a 1.0.3 corrigiu a coluna nuts2 dos microdados, que passou a seguir as regiões NUTS II de 2013. As pessoas e os agregados gerados são os mesmos nas quatro versões. Os ficheiros das versões 1.0.0 e 1.0.1 continuam no GitHub, como registo, na lista de versões; a 1.0.2 não chegou a ser publicada lá.

Se, depois de ler esta página, concluíres que estes dados não servem o teu estudo, a visita valeu na mesma: é melhor saber agora do que depois de tirar conclusões.

Pessoas

10 340 441 linhas, uma por pessoa gerada, incluindo quem vive em alojamentos coletivos (is_institutional = 1, registos parciais).

Agregados

4 154 571 linhas, uma por agregado gerado. Cada alojamento coletivo conta como um agregado (is_institutional = 1). As perguntas do site sobre agregados contam só os agregados privados (is_institutional = 0).

Ligação

Pessoas e agregados ligam-se por (freguesia, synthetic_hh_id): o identificador do agregado só é único dentro de cada freguesia.

Freguesias

3 092 freguesias publicadas, nenhuma suprimida pelo tamanho. As pequenas levam um nível de qualidade em vez de serem retiradas.

Códigos

Códigos DICOFRE de 6 caracteres da CAOP 2021 (as freguesias dos Censos 2021). Oito códigos de Barcelos têm letras (0302FA a 0302FH): lê a coluna como texto, não como número. Junta tabelas pelo código (municipio), nunca pelo nome: os nomes do pacote vêm da geografia dos Censos 2021 do INE (por exemplo, «Calheta (R.A.M.)» e «Lagoa (R.A.A.)») e diferem dos do site (CAOP 2021), onde há dois concelhos chamados Lagoa.

Depois de 2025

Desde as eleições autárquicas de outubro de 2025 (Lei n.º 25-A/2025), 135 uniões de freguesias foram desagregadas em 302 freguesias. Esta versão usa as freguesias de 2021: para juntar dados posteriores (os resultados das autárquicas de 2025, a CAOP 2024 ou 2025), precisas de uma tabela de correspondência entre os códigos de 2021 e os atuais.

Regiões

A coluna nuts2 é a região NUTS II (2013) da freguesia. Até à versão 1.0.2 era um agrupamento por distrito; a 1.0.3 corrigiu-a (ver as erratas).

Concelhos

308 concelhos, com o código no formato DDCC00.

Partição

No pacote, os microdados estão divididos por distrito (os dois primeiros dígitos do código da freguesia), com uma cópia nacional consolidada.

Primeiros passos

Três exemplos que ligam pessoas a agregados; o último reproduz um cartão do site. Como nas perguntas do site sobre agregados, ficam só os agregados privados (is_institutional = 0). Se publicares tabelas feitas com estes dados, segue as regras do site: diz o nível de qualidade de cada freguesia, lê com mais cuidado as categorias com poucas pessoas e as freguesias de nível C, e não faças ordenações nem comparações «mais do que» a partir de uma única execução.

-- DuckDB: pessoas por tamanho do agregado, numa freguesia
SELECT h.hh_size_bin, count(*) AS pessoas
FROM 'pt-synthpop-v1.0.3-persons.parquet' AS p
JOIN 'pt-synthpop-v1.0.3-households.parquet' AS h
  USING (freguesia, synthetic_hh_id)
WHERE p.freguesia = '060318'
  -- só agregados privados, como no site: os alojamentos coletivos
  -- (is_institutional = 1) contam como um agregado e quase todos caem em «5»
  AND h.is_institutional = 0
GROUP BY h.hh_size_bin
ORDER BY h.hh_size_bin;

# Python (pandas + pyarrow)
import pandas as pd

persons = pd.read_parquet("pt-synthpop-v1.0.3-persons.parquet")
households = pd.read_parquet("pt-synthpop-v1.0.3-households.parquet")

# synthetic_hh_id só é único dentro de cada freguesia
merged = persons.merge(
    households, on=["freguesia", "synthetic_hh_id"], suffixes=("", "_hh")
)

# só agregados privados, como no site (os alojamentos coletivos têm is_institutional = 1)
private = merged[merged["is_institutional_hh"] == 0]

-- DuckDB: reproduz um cartão do site, «Quantas pessoas com 65 ou mais anos vivem sozinhas?»
-- em Moreira de Cónegos (030831); deve dar 0,149, o 14,9% da página
SELECT avg(CASE WHEN h.hh_size = 1 THEN 1 ELSE 0 END) AS vivem_sozinhas
FROM 'pt-synthpop-v1.0.3-persons.parquet' AS p
JOIN 'pt-synthpop-v1.0.3-households.parquet' AS h
  USING (freguesia, synthetic_hh_id)
WHERE p.freguesia = '030831'
  AND p.age >= 65
  AND h.is_institutional = 0;

De onde vem cada coluna

G

Gerado. Produzido pelo modelo. Pode estar ajustado a uma tabela do INE por freguesia ou não; a descrição da coluna diz qual é o caso.

D

Derivado. Calculado a partir de outra coluna por uma regra fixa (um agrupamento, uma etiqueta). Tão fiável como a coluna de origem.

C

Tornado coerente. Recalculado depois de gerado para ser coerente com o resto do registo; por exemplo, o tamanho do agregado é o número das suas pessoas.

X

Geográfico. Atribuído a partir do código da freguesia (CAOP 2021). Um identificador, não um resultado do modelo.

key

Chave. Liga pessoas a agregados.

flag

Indicador. Um indicador 0/1.

• Qualidade A776 freguesias
• Qualidade B705 freguesias
• Qualidade C1 611 freguesias

O que diz cada coluna do ficheiro de qualidade

O ficheiro quality.csv, que o README do pacote manda ler primeiro. Origem: INE (contagem publicada), gerado (contado na população gerada), avaliação (medido contra as tabelas do INE) ou geográfico.

freguesiaGeográfico

Código DICOFRE da freguesia (6 caracteres, CAOP 2021). Lê-o como texto.

freguesia_nameGeográfico

Nome da freguesia, em maiúsculas.

municipio, municipio_nameGeográfico

Código do concelho (DDCC00) e nome segundo o INE (2021).

district, nuts2Geográfico

Distrito (2 dígitos) e região NUTS II de 2013 (corrigida na 1.0.3).

populationGerado

Pessoas geradas na freguesia, incluindo quem vive em alojamentos coletivos. Somadas, dão as pessoas da versão.

census_populationINE

Residentes segundo o INE (o total da tabela por sexo e idade dos Censos 2021). É a contagem que o site mostra como «residentes (INE)».

publication_populationAvaliação

A menor das duas contagens anteriores: é a que decide os limiares de 500 e 2 000 residentes dos níveis. population e census_population não coincidem em todas as freguesias (a população gerada não reproduz exatamente o total do INE; os números estão abaixo da tabela); o pacote não regista a razão freguesia a freguesia.

n_householdsGerado

Agregados gerados, contando cada alojamento coletivo como um. Não é a contagem de agregados privados do INE.

n_institutional_personsGerado

Pessoas em alojamentos coletivos, acrescentadas a partir das contagens do INE.

pct_children_u15Gerado

Proporção (de 0 a 1) de pessoas geradas com menos de 15 anos.

quality_tierAvaliação

Nível de qualidade: A, B ou C.

person_srmse_medianAvaliação

Erro típico da freguesia: a mediana dos 12 erros (SRMSE) das tabelas de pessoas do ajuste, um por tabela (0 seria igual às tabelas). É o primeiro critério dos níveis. Não é o «erro do ajuste» do gráfico por tamanho da página de qualidade, que junta todas as células das 12 tabelas: as medianas por classe dos dois não coincidem.

worst_constraint, worst_constraint_srmseAvaliação

A tabela de pessoas com o maior erro e esse erro (o segundo critério dos níveis), contando também a idade ano a ano. Na maior parte das freguesias é a idade ano a ano (srmse_p_age_single). Que tabela é cada código: abaixo da tabela.

suppression_reasonVersão

Vazio em todas as freguesias: nenhuma é suprimida.

fallback_geographyVersão

Nas freguesias de nível C, o código do concelho, para quem preferir agregar ao concelho. O site não o usa: todas as freguesias respondem com os seus próprios números.

engine, model_version, run_dateVersão

O motor, a versão do modelo e a data da execução.

O total gerado nem sempre é o do INE: em 762 freguesias difere, entre 119 pessoas a menos e 30 a mais; no país, são 2 625 pessoas a menos (10 340 441 geradas, contra 10 343 066 residentes segundo o INE). Os níveis de qualidade usam a menor das duas contagens, a contagem de publicação.

Como sabemos que funciona?

# 1. Os ficheiros descarregados, contra SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

# 2. O conteúdo do pacote, na pasta que contém checksums.sha256
sha256sum -c checksums.sha256

# 3. A lista de somas é a publicada: deve imprimir
# 0992bcfec9595df4fc2102349a6692e570ebc4322377e85438d795dc5a4ab8d8
sha256sum checksums.sha256

No macOS, usa shasum -a 256 em vez de sha256sum.

As correções a esta versão ficam registadas nas erratas. Para reportar um problema, abre uma questão no GitHub ou escreve para info@estimador.pt. A ficha do modelo tem a descrição técnica completa.

Como foi feita a população