Can I use these data?

Release

pt-synthpop 1.0.3, dated 5 October 2026 (published on GitHub on 6 October 2026)

Reference year

2021: generated from INE’s 2021 Census.

Model

Engine v10, a single run. sha256 062e2ad784886b7287536233f853db151c57615d2b1a952fb2e12368581e76d3

Code

Commit 4bf0819 of the packaging code; the repository is not public yet.

Previous releases

1.0.3 replaced three releases dated 5 October (1.0.2 never reached GitHub); the generated population is the same in all of them.

What changed between releases

Release 1.0.3 replaced releases 1.0.0, 1.0.1 and 1.0.2, all of 5 October 2026. Release 1.0.0 applied launch thresholds to the site’s answers that hid about half of the parish answers; 1.0.1 removed them, so every parish answers with its own figures; 1.0.2 asked the household questions of private households and fixed the presentation; 1.0.3 corrected the microdata’s nuts2 column to the 2013 NUTS II regions. The generated people and households are the same in all four releases. The files of releases 1.0.0 and 1.0.1 stay on GitHub, as a record, in the list of releases; 1.0.2 was never published there.

If, after reading this page, you conclude that these data do not suit your study, the visit was still worth it: better to know now than after drawing conclusions.

Persons

10,340,441 rows, one per generated person, including residents of collective quarters (is_institutional = 1, partial records).

Households

4,154,571 rows, one per generated household. Each collective living quarter counts as one household (is_institutional = 1). The site’s household questions count private households only (is_institutional = 0).

Join

Persons and households join on (freguesia, synthetic_hh_id): the household id is unique only within a parish.

Parishes

3,092 parishes published, none suppressed for size. Small ones carry a quality tier instead of being withheld.

Codes

6-character DICOFRE codes from CAOP 2021 (the 2021 Census parishes). Eight Barcelos codes contain letters (0302FA to 0302FH): read the column as text, not as a number. Join tables on the code (municipio), never on the name: the package’s names come from INE’s 2021 Census geography (for example “Calheta (R.A.M.)” and “Lagoa (R.A.A.)”) and differ from the site’s (CAOP 2021), where two municipalities are called Lagoa.

After 2025

Since the October 2025 local elections (Law 25-A/2025), 135 parish unions have been split into 302 parishes. This release uses the 2021 parishes: to join later data (the 2025 local election results, CAOP 2024 or 2025) you need a correspondence table between the 2021 codes and the current ones.

Regions

The nuts2 column is the parish’s NUTS II (2013) region. Up to release 1.0.2 it was a district grouping; 1.0.3 corrected it (see the errata).

Municipalities

308 municipalities, coded as DDCC00.

Partitioning

In the package the microdata are partitioned by district (the first two digits of the parish code), with a consolidated national copy.

First steps

Three examples that join persons to households; the last one reproduces a card on the site. As in the site’s household questions, they keep private households only (is_institutional = 0). If you publish tables made from these data, follow the site’s rules: state each parish’s quality tier, read categories with few people and tier C parishes with more care, and make no rankings or “more than” comparisons from a single run.

-- DuckDB: persons by household size, in one parish
SELECT h.hh_size_bin, count(*) AS persons
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'
  -- private households only, as on the site: collective quarters
  -- (is_institutional = 1) count as one household and almost all fall under "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 is unique only within a parish
merged = persons.merge(
    households, on=["freguesia", "synthetic_hh_id"], suffixes=("", "_hh")
)

# private households only, as on the site (collective quarters have is_institutional = 1)
private = merged[merged["is_institutional_hh"] == 0]

-- DuckDB: reproduces a card on the site, “How many people aged 65 or over live alone?”
-- in Moreira de Cónegos (030831); it should return 0.149, the page’s 14.9%
SELECT avg(CASE WHEN h.hh_size = 1 THEN 1 ELSE 0 END) AS living_alone
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;

Where each column comes from

G

Generated. Produced by the model. It may or may not be fitted to an INE parish table; the column’s description says which.

D

Derived. Computed from another column by a fixed rule (a grouping, a label). As reliable as its parent column.

C

Consistency-enforced. Recomputed after generation to agree with the rest of the record; for example, household size is the number of its persons.

X

Geographic. Assigned from the parish code (CAOP 2021). An identifier, not a model output.

key

Key. Links persons to households.

flag

Flag. A 0/1 indicator.

• Quality A776 parishes
• Quality B705 parishes
• Quality C1,611 parishes

What each column of the quality file says

The quality.csv file, which the package README says to read first. Source: INE (a published count), generated (counted in the generated population), evaluation (measured against INE’s tables) or geographic.

freguesiaGeographic

Parish DICOFRE code (6 characters, CAOP 2021). Read it as text.

freguesia_nameGeographic

Parish name, in capitals.

municipio, municipio_nameGeographic

Municipality code (DDCC00) and INE’s (2021) name.

district, nuts2Geographic

District (2 digits) and 2013 NUTS II region (corrected in 1.0.3).

populationGenerated

People generated in the parish, residents of collective quarters included. Summed, they give the release’s persons.

census_populationINE

Residents according to INE (the total of the 2021 Census sex × age table). It is the count the site shows as “residents (INE)”.

publication_populationEvaluation

The smaller of the two counts above: it decides the tiers’ 500 and 2,000-resident thresholds. population and census_population do not agree in every parish (the generated population does not reproduce INE’s total exactly; the figures are under the table); the package does not record the reason parish by parish.

n_householdsGenerated

Generated households, counting each collective living quarter as one. It is not INE’s count of private households.

n_institutional_personsGenerated

People in collective living quarters, appended from INE’s counts.

pct_children_u15Generated

Share (from 0 to 1) of generated people under 15.

quality_tierEvaluation

Quality tier: A, B or C.

person_srmse_medianEvaluation

The parish’s typical error: the median of the 12 errors (SRMSE) of the fitted person tables, one per table (0 would match the tables). It is the tiers’ first criterion. It is not the “fit error” in the quality page’s chart by size, which pools all the cells of the 12 tables: the two give different medians per band.

worst_constraint, worst_constraint_srmseEvaluation

The person table with the largest error, and that error (the tiers’ second criterion), single-year age included. In most parishes it is single-year age (srmse_p_age_single). Which table each code is: under the table.

suppression_reasonRelease

Empty for every parish: none is suppressed.

fallback_geographyRelease

For tier C parishes, the municipality code, for readers who prefer to aggregate to it. The site does not use it: every parish answers with its own figures.

engine, model_version, run_dateRelease

The engine, the model version and the run date.

The generated total is not always INE’s: in 762 parishes it differs, from 119 people fewer to 30 more; nationally, there are 2,625 people fewer (10,340,441 generated, against 10,343,066 residents according to INE). The quality tiers use the smaller of the two counts, the publication count.

How do we know it works?

# 1. The downloaded files, against SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

# 2. The package contents, in the folder holding checksums.sha256
sha256sum -c checksums.sha256

# 3. The list of sums is the published one: it should print
# 0992bcfec9595df4fc2102349a6692e570ebc4322377e85438d795dc5a4ab8d8
sha256sum checksums.sha256

On macOS, use shasum -a 256 instead of sha256sum.

Corrections to this release are recorded in the errata. To report a problem, open a GitHub issue or write to info@estimador.pt. The model card has the full technical account.

How the population was made