02Dasymetric - Population Disaggregation Lab

User manual, version 0.1.2 (2026-11-16). QGIS 3.28 to 4.x. GPL-2.0-or-later. Yusuf Eminoğlu (Geophilo).

1. What the plugin does

Census and register counts arrive in administrative zones that rarely match the units a planner needs: grid cells, blocks, buildings, hazard footprints, catchments. 02Dasymetric moves those counts into finer units inside QGIS. It takes source zones with one or more count fields and, optionally, building footprints, a built-up raster (GHS-BUILT-S or GHS-BUILT-V), a gridded population product (GHS-POP or WorldPop) and a land-cover raster (ESA WorldCover or any class raster), and produces a population surface on an equal-area grid with seven methods, building-level estimates, estimates for any target polygons, an accuracy assessment and a self-contained HTML report.

Every method keeps each zone total exactly: allocation runs over (cell, zone) pairs whose shares come from a supersampled rasterisation, and a run whose largest relative zone mass error \(\max_z \bigl|\sum_i x_{iz} - P_z\bigr| / P_z\) exceeds \(10^{-9}\) is rejected. Cells outside every zone are nodata; inhabited cells without people are 0.

The same steps are available in the lab dock (toolbar button 02Dasymetric lab) and as fifteen Processing algorithms in the provider 02Dasymetric, which also run in the graphical modeller and in batch mode.

Why this plugin

The methods that move counts into finer units are well documented (areal weighting, binary and multi-class dasymetric mapping, intelligent dasymetric mapping, Tobler's pycnophylactic interpolation, building-based allocation), but inside QGIS they are scattered or absent. A Hub search on 14 Nov 2026 for "dasymetric", "pycnophylactic", "disaggregation", "areal interpolation", "GHSL" and "WorldPop" found one areal-weighting tool with an optional binary mask (PlanX), raster-to-raster random-forest downscaling without a zone mass constraint, and tools that consume WorldPop for other purposes. Nothing implemented pycnophylactic interpolation, nothing fetched GHSL, and nothing reported accuracy. Outside QGIS the methods live in libraries (PySAL tobler, CRAN pycno, populR, areal) and in the ArcGIS-only Intelligent Dasymetric Mapping toolbox. 02Dasymetric carries one study end to end in one panel and in Processing, with no extra installs.

2. Install

From QGIS: Plugins > Manage and Install Plugins, search for 02Dasymetric, install. From a release zip: Plugins > Manage and Install Plugins > Install from ZIP.

Requirements: QGIS 3.28 or later, QGIS 4 included (Qt5 and Qt6). The plugin uses only what every QGIS install ships: qgis.core, GDAL/OGR, NumPy and PyQt. SciPy is used for non-negative least squares when it is importable; a built-in Lawson-Hanson solver gives identical densities without it. No Python package has to be installed.

3. Units, grid and working CRS

A count per cell is only a density when every cell has the same area, so the plugin works on an equal-area grid in metres. The working CRS is chosen from the zone extent:

Every vector input is transformed into the working CRS and every raster is warped onto the grid with GDAL: sum resampling for count rasters (GHS-POP, WorldPop, GHS-BUILT-S, GHS-BUILT-V) so totals are kept, average for shares, and class fractions for land cover (supersampled nearest neighbour, then block counting). Areas are planar areas in the working CRS. The grid origin snaps to multiples of the cell size, so a translation by whole cells reproduces the same arrays.

Zone fractions. Each cell is split into \(s \times s\) sub-cells (supersampling \(s\), default \(s = 4\)), GDAL burns the zone index into the sub-cells whose centre lies inside a zone, and the sub-cells are counted per (cell, zone) pair:

\[ f_{iz} = \frac{n_{iz}}{s^2}, \qquad \tilde A_z = \sum_i f_{iz}\,a \tag{1} \]

where \(n_{iz}\) is the number of sub-cells of cell \(i\) whose centre lies in zone \(z\), \(f_{iz}\) the share of cell \(i\) inside zone \(z\), \(a\) the cell area and \(\tilde A_z\) the rasterised zone area. \(\tilde A_z\) (not the polygon area \(A_z\)) is the allocation denominator of a zone, so the zone total is exact by construction. A zone too small to hold one sub-cell centre is placed at its point on surface with \(f_{iz} = \min(1, A_z / a)\) and listed in the log. When \(n_y\,n_x\,s^2 > 64 \times 10^6\) (\(n_y \times n_x\) grid cells), the supersampling is reduced and the log says so.

GeoTIFF output is Float32 by default (relative round trip about \(10^{-7}\)) or Float64 on request.

4. The lab dock, page by page

The lab is a dock on the right of the QGIS window with a vertical icon rail. A study runs top to bottom; every step can be repeated. Long work (reading layers, downloads, runs, assessments, exports) runs as a QGIS background task with a progress strip and a Cancel button, so the dock never freezes. Results go to a 02Dasymetric layer group with one subgroup per run.

1. Zones

Source zones: the polygon layer that carries the counts, its key field and one or more numeric count fields (a checklist). Load demo city adds the synthetic city of section 10. Working grid: cell size chips (25, 50, 100, 250 m) and a spin box, supersampling, and an optional CRS override; a badge shows the working CRS and why it was chosen (for example "UTM 35N - extent inside one zone"). Zone summary: zones, total count, median zone area, mean density per \(\mathrm{km^2}\) and grid cells, plus the share of zones with a valid count (NULL counts are skipped and reported, never treated as 0).

2. Ancillary

Four cards, each with a status pill (missing, local, downloaded) and a licence and citation line.

3. Method

Methods: chips for the seven methods; a method whose input is missing is switched off and its tooltip says why. Parameters shows only the parameters of the chosen methods: binary mask source and threshold; class mode (IDM, regression, fixed), IDM minimum share and minimum zones; continuous exponents and the optional mask; pycnophylactic iterations, tolerance, relaxation and boundary. Outputs: optional target polygons and the GeoTIFF precision. Run disaggregation runs every chosen method on every ticked count field; the run table lists the mass error, fallback zones and people, inhabited cells and pycnophylactic iterations per method.

4. Results

Surfaces: one GeoTIFF layer per method with show/hide and Active buttons. People per cell: a histogram of the occupied cells of one surface, KPIs (occupied cells, median, largest cell, sum) and Restyle surfaces (quantile classes on an amber ramp, lighter on a dark theme). Class densities: people per \(\mathrm{km^2}\) of each land-cover class from the multi-class method. Buildings and targets: buildings with people, the integer total and the target polygons summary.

5. Accuracy

Three modes. Validation zones: finer polygons with a known count (for example neighbourhoods); every surface is summed over them and compared. Self-validation: aggregate-up, with the block side (0 = automatic). Prior agreement: the population prior summed per census zone over the census count. The comparison table holds RMSE, MAE, bias, MdAPE, \(R^2\) and the misallocated share per method with the best value per column in amber; the observed-against-estimated scatter has a 1:1 line and a method switcher; the error layer is added with a diverging style. When only the accuracy settings changed since the last run, the assessment reuses that run and computes the accuracy stage only.

6. Report

Export report writes the self-contained HTML report (inline CSS, SVG and an embedded KaTeX bundle that typesets every formula as in this manual, offline, no external resources) and offers a link to open it. GeoTIFF per method (plus the method spread, see section 9), GeoPackage (buildings, targets, error layer, run table and accuracy metrics) and Metrics CSV (one row per count field and method: total, mass error, fallbacks, iterations and, after an assessment, every accuracy metric).

Help

Workflow, which method when, formulas, data licences and citations, method references and links to this manual and the repository. The plugin menu also has a Manual entry.

5. Methods and formulas

Notation: source zone \(z\) with count \(P_z\) and planar area \(A_z\); grid cell \(i\) with area \(a\) (the same for every cell of the equal-area grid); \(f_{iz}\) the share of cell \(i\) inside zone \(z\), equation (1); ancillary weight \(w_i \ge 0\). Every method allocates over (cell, zone) pairs and sums per cell:

\[ x_{iz} = P_z\,\frac{f_{iz}\,w_i}{\sum_j f_{jz}\,w_j}, \qquad s_i = \sum_z x_{iz}, \qquad \sum_i x_{iz} = P_z \tag{2} \]

where \(x_{iz}\) is the count zone \(z\) places in cell \(i\), the sum over \(j\) runs over the cells of zone \(z\), and \(s_i\) is the people in cell \(i\), the value of the output surface. A zone whose ancillary weight is zero everywhere (\(\sum_j f_{jz}\,w_j = 0\)) falls back to areal weighting; the run lists these zones and the people they hold.

MethodWhat it doesFormulaReferences
Areal weighting
areal
Spread each zone's count evenly over its area (baseline).\(x_{iz} = P_z\,\frac{f_{iz}\,a}{\sum_j f_{jz}\,a}\)Goodchild & Lam 1980
Binary dasymetric
binary
Spread each zone's count evenly over its inhabited cells only.\(x_{iz} = P_z\,\frac{f_{iz}\,m_i}{\sum_j f_{jz}\,m_j},\ m_i \in \{0, 1\}\)Langford & Unwin 1994; Eicher & Brewer 2001; Mennis 2003
Multi-class dasymetric
classes
Weight cells by land-cover class densities (fixed, intelligent sampling or regression).\(w_i = \sum_c \varphi_{ic}\,d_c\); IDM: \(d_c = \sum_{z \in S_c} P_z \big/ \sum_{z \in S_c} A_z\); regression: \(P_z = \sum_c d_c\,A_{zc}\) (NNLS); \(x_{iz} = P_z\,\frac{f_{iz}\,w_i}{\sum_j f_{jz}\,w_j}\)Mennis 2003; Mennis & Hultgren 2006; Langford et al. 1991; Yuan et al. 1997; Lawson & Hanson 1974
Continuous ancillary
continuous
Weight cells by built-up surface/volume or a population prior, rescaled to the census.\(w_i = \prod_k \bigl(q_{ik} / \bar q_k\bigr)^{\beta_k}\); \(x_{iz} = P_z\,\frac{f_{iz}\,w_i}{\sum_j f_{jz}\,w_j}\)Stevens et al. 2015; Leyk et al. 2019
Building-based
buildings
Split each zone's count over its buildings by count, footprint, floor area, volume or a field.\(P_b = P_z\,\frac{w_b}{\sum_{b' \in z} w_{b'}}\); integers by largest remainder per zoneLwin & Murayama 2009; Zandbergen & Ignizio 2010
Pycnophylactic
pycno
The smoothest non-negative surface that keeps every zone total (Tobler).\(v_i \leftarrow (1-\lambda)\,v_i + \lambda\,\bar v_i\); \(v_i \leftarrow v_i + \bigl(P_z - \sum_{j \in z} v_j\bigr)/n_z\); \(v_i \ge 0\); rescale to \(P_z\)Tobler 1979
Dasymetric-pycnophylactic
pycno_dasy
Pycnophylactic smoothing over inhabited cells only; the rest stays 0.as pycnophylactic, with cells \(m_i = 0\) fixed at 0 and left out of the means and correctionsKim & Yao 2010; Tobler 1979

Areal weighting

The baseline: each zone's count spread evenly over its area, equation (2) with \(w_i = 1\). Every other method is judged against it.

\[ x_{iz} = P_z\,\frac{f_{iz}\,a}{\sum_j f_{jz}\,a} = P_z\,\frac{f_{iz}}{\sum_j f_{jz}} \tag{3} \]

Binary dasymetric

Only inhabited cells receive people:

\[ x_{iz} = P_z\,\frac{f_{iz}\,m_i}{\sum_j f_{jz}\,m_j}, \qquad m_i = \begin{cases} 1 & \text{if } g_i > t \\ 0 & \text{otherwise} \end{cases} \tag{4} \]

where \(m_i\) is the inhabited mask, \(t\) the mask threshold (default \(t = 0\)) and \(g_i\) the value of the mask source in cell \(i\): the summed weight of the eligible buildings whose point on surface lies in the cell (with \(t = 0\): an eligible building is present), the built-up value, or the land-cover weight \(\sum_c \varphi_{ic}\,\omega_c\), with \(\omega_c\) the relative density of class \(c\) in the class table.

Multi-class dasymetric

The cell weight is the class-fraction mix of class densities:

\[ w_i = \sum_c \varphi_{ic}\,d_c, \qquad A_{zc} = \sum_i f_{iz}\,\varphi_{ic}\,a \tag{5} \]

where \(\varphi_{ic}\) is the fraction of cell \(i\) in land-cover class \(c\) (supersampled, not the majority class), \(d_c\) the density of class \(c\) and \(A_{zc}\) the area of class \(c\) in zone \(z\), in \(\mathrm{km^2}\). Three ways to get \(d_c\):

The class density table lists \(d_c\) in people per \(\mathrm{km^2}\) and where each value came from (sampled, regression, zero, fixed).

Continuous ancillary weights

\[ w_i = \prod_k \Bigl( \frac{q_{ik}}{\bar q_k} \Bigr)^{\beta_k}, \qquad \bar q_k = \frac{1}{|\{i : q_{ik} > 0\}|} \sum_{i : q_{ik} > 0} q_{ik} \tag{9} \]

where \(q_{ik}\) is the value of ancillary layer \(k\) (built-up surface or volume, or a population prior) in cell \(i\), warped onto the grid, \(\bar q_k\) its mean over the positive cells and \(\beta_k\) its exponent (default \(\beta_k = 1\)). Cells without data get \(w_i = 0\); optionally \(w_i\) is multiplied by the binary mask \(m_i\). With a population product as the only layer and \(\beta = 1\) this is the census-constrained rescaling step of top-down gridded population products.

Building-based allocation

\[ P_b = \sum_z P_z\,\frac{w_b\,\sigma_{bz}}{\sum_{b'} w_{b'}\,\sigma_{b'z}}, \qquad w_b \in \bigl\{\,1,\ A_b,\ A_b F_b,\ A_b H_b,\ \text{field value} \bigr\} \tag{10} \]

where \(P_b\) is the estimate of building \(b\), \(w_b\) its weight (count, footprint \(A_b\), floor area \(A_b F_b\), volume \(A_b H_b\) or a field such as dwellings), \(F_b\) its floors, \(H_b\) its height (the height field, else \(F_b\,h_s\)) and \(\sigma_{bz}\) the share of building \(b\) assigned to zone \(z\): 1 for the zone holding its point on surface and 0 elsewhere, or the share of its footprint inside \(z\) when split by overlap area. Floors come from the floors field, else from the height:

\[ F_b = \max\Bigl(1,\ \Bigl\lfloor \frac{H_b}{h_s} + \frac12 \Bigr\rfloor \Bigr) \tag{11} \]

with \(h_s\) the storey height (default \(3\,\mathrm{m}\)), so halves are rounded up; unknown floors take the zone median of known floors, else 1. Integer counts per zone by the largest remainder method sum exactly to \(\operatorname{round}(P_z)\). The grid surface puts each \(P_b\) in the cell of its point on surface; zones without an eligible building fall back to areal weighting on the grid and are reported.

Pycnophylactic interpolation

Starts from areal weighting on the majority-zone raster, \(v_i = P_z / n_z\), and repeats, for every cell \(i\) of zone \(z\):

\[ \begin{aligned} \bar v_i &= \frac{1}{|N(i)|} \sum_{j \in N(i)} v_j \\ v_i &\leftarrow (1-\lambda)\,v_i + \lambda\,\bar v_i \\ v_i &\leftarrow v_i + \frac{P_z - \sum_{j \in z} v_j}{n_z} \\ v_i &\leftarrow \max(0,\ v_i) \\ v_i &\leftarrow v_i\,\frac{P_z}{\sum_{j \in z} v_j} \end{aligned} \tag{12} \]

where \(N(i)\) are the four rook neighbours of cell \(i\) (outside the study area \(v_j = 0\) for the zero boundary and \(v_j = v_i\), a mirror, for the free boundary), \(\lambda\) the relaxation (default \(0.5\)) and \(n_z\) the number of cells of zone \(z\). It stops when

\[ \max_i |\Delta v_i| < \tau\,\bar v \tag{13} \]

with \(\Delta v_i\) the change in one iteration, \(\tau\) the tolerance (default \(10^{-4}\)) and \(\bar v\) the mean cell value, or at the iteration limit. The volume is kept at every iteration. With the zero boundary the density falls towards the study edge, as Tobler's condition implies; the free boundary keeps a single zone uniform.

Dasymetric-pycnophylactic

As above, but cells with \(m_i = 0\) are fixed at 0 and left out of \(N(i)\), \(n_z\) and the zone corrections (Kim and Yao 2010). A zone without an inhabited cell is smoothed over all its cells and listed as a fallback.

Which method when

6. Accuracy assessment

Validation zones: disaggregate from the coarse source zones, aggregate every surface to finer zones with known counts (e.g. districts to neighbourhoods) and compare. When the two levels hold different totals the report says so.

Aggregate-up self-validation (one level of data): merge the source zones into deterministic square-block groups (block side \(L = 2\sqrt{\operatorname{median}_z A_z}\) by default, about four zones per group, the block grid starting at the top-left of the zones), disaggregate from the groups with the same ancillary data and compare with the original zone counts. Groups holding a single zone carry no information and are left out (Fisher and Langford 1995; Kim and Yao 2010).

Metrics. With \(y_u\) the observed and \(\hat y_u\) the estimated count of unit \(u\), the error \(e_u = \hat y_u - y_u\) and \(n\) the units where both are known:

\[ \mathrm{RMSE} = \sqrt{\frac{1}{n} \sum_u e_u^2}, \qquad \mathrm{MAE} = \frac{1}{n} \sum_u |e_u|, \qquad \mathrm{bias} = \frac{1}{n} \sum_u e_u \tag{14} \] \[ \mathrm{MAPE} = \operatorname*{mean}_{u : y_u > 0} \frac{100\,|e_u|}{y_u}, \qquad \mathrm{MdAPE} = \operatorname*{median}_{u : y_u > 0} \frac{100\,|e_u|}{y_u} \tag{15} \] \[ \text{CV-RMSE} = \frac{\mathrm{RMSE}}{\bar y}, \qquad R^2 = 1 - \frac{\sum_u e_u^2}{\sum_u (y_u - \bar y)^2} \tag{16} \] \[ r = \frac{\sum_u (y_u - \bar y)(\hat y_u - \bar{\hat y})}{\sqrt{\sum_u (y_u - \bar y)^2}\,\sqrt{\sum_u (\hat y_u - \bar{\hat y})^2}} \tag{17} \] \[ \mathrm{TAE} = \sum_u |e_u|, \qquad \text{misallocated share} = \frac{\mathrm{TAE}}{2 \sum_u y_u} \tag{18} \]

where \(\bar y\) and \(\bar{\hat y}\) are the means of the observed and estimated counts. MAPE and MdAPE (in percent) use \(y_u > 0\) only; the excluded count is reported, never a division by zero. \(r\) is Pearson's correlation; the misallocated share is the share of people placed in the wrong unit. An undefined metric is NULL. Report MAE beside RMSE (Willmott and Matsuura 2005). The best method per metric has the lowest error, the highest \(R^2\) and \(r\), and the smallest \(|\mathrm{bias}|\).

Prior agreement (agreement, not accuracy): GHS-POP or WorldPop summed per census zone divided by the census count,

\[ \rho_z = \frac{\sum_i f_{iz}\,p_i}{P_z} \tag{19} \]

where \(p_i\) is the prior in cell \(i\) (warped with sum resampling); zones with \(P_z\) NULL or 0 get no ratio. Reported: the median of \(\rho_z\), the interquartile range \(Q_3 - Q_1\) and the share of zones with \(|\rho_z - 1| \le 0.2\) (within \(\pm 20\,\%\)).

7. Data sources and licences

All downloads go through the QGIS network manager (proxy and authentication settings) into the cache folder, and every fetch records source, URL, licence and citation in the run log and the report. Sizes are shown before anything is downloaded; cached files are reused offline.

ProductAccessLicenceCitation
GHS-POP R2023A, 100 m, Mollweide (ESRI:54009), epochs 1975-2030 every 5 years1000 km tiles from the JRC open-data server (zip, inner GeoTIFF read through /vsizip/); missing ocean tiles (HTTP 404) are listed and read as zeroCC BY 4.0Schiavina, Freire, MacManus (2023), European Commission JRC, doi:10.2905/2FF68A52-5B5B-4A22-8F40-C41DA8332CFE
GHS-BUILT-S R2023A (built-up \(\mathrm{m^2}\) per cell), same gridas GHS-POPCC BY 4.0Pesaresi (2023), JRC, doi:10.2905/9F06F36F-4B11-47EC-ABB0-4F8B7B1D72EA
GHS-BUILT-V R2023A (built-up \(\mathrm{m^3}\) per cell), same gridas GHS-POPCC BY 4.0Pesaresi, Politis (2023), JRC, doi:10.2905/AB2F107A-03CD-47A3-85E5-139D8EC63283
WorldPop R2025A constrained, 3 arc-second, 2015-2030country file found through the WorldPop REST catalogue (ISO3 code); the server serves no byte ranges, so the file is downloaded whole. Labelled alpha by WorldPop.CC BY 4.0Bondarenko et al. (2025), doi:10.5258/SOTON/WP00839
ESA WorldCover 10 m, 2021 v200 (and 2020 v100)\(3^\circ \times 3^\circ\) cloud-optimised GeoTIFF tiles CC BY 4.0Zanaga et al. (2022), doi:10.5281/zenodo.7254221 (2020: doi:10.5281/zenodo.5571936)
Building footprintsyour own layer (OSM, cadastre, Overture); the plugin downloads no buildings as suppliedas supplied

GHSL and WorldCover can also be read remotely through GDAL /vsicurl/ (opt-in stream mode); the QGIS proxy is then copied into the GDAL configuration for the duration of the read only.

8. Processing algorithms

Provider 02Dasymetric (id zero2dasymetric). Each algorithm wraps one step of the core; the method algorithms run the same staged pipeline as the dock for one method and one count field, so their surfaces are identical to the dock's. Outputs are not styled by the algorithms. From the Python console, for example:

processing.run("zero2dasymetric:areal_weighting", {
    "ZONES": zones, "COUNT_FIELD": "population", "CELL": 100,
    "OUTPUT": "TEMPORARY_OUTPUT"})

Population disaggregation lab (whole study) zero2dasymetric:disaggregation_lab

Group: Study.

The whole study of the dock in one step (core.pipeline.run_lab): working CRS and grid, zone fractions, ancillary data, every chosen method on every count field with the per-zone mass check (a run is rejected above a relative error of \(10^{-9}\)), optional target polygons, accuracy assessment, one GeoTIFF per method and count field, building estimates and a self-contained HTML report naming every formula, data source, licence and reference.

Methods: Areal weighting \(x_{iz} = P_z\,\frac{f_{iz}\,a}{\sum_j f_{jz}\,a}\); Binary dasymetric \(x_{iz} = P_z\,\frac{f_{iz}\,m_i}{\sum_j f_{jz}\,m_j},\ m_i \in \{0, 1\}\); Multi-class dasymetric \(w_i = \sum_c \varphi_{ic}\,d_c\); IDM: \(d_c = \sum_{z \in S_c} P_z \big/ \sum_{z \in S_c} A_z\); regression: \(P_z = \sum_c d_c\,A_{zc}\) (NNLS); \(x_{iz} = P_z\,\frac{f_{iz}\,w_i}{\sum_j f_{jz}\,w_j}\); Continuous ancillary \(w_i = \prod_k \bigl(q_{ik} / \bar q_k\bigr)^{\beta_k}\); \(x_{iz} = P_z\,\frac{f_{iz}\,w_i}{\sum_j f_{jz}\,w_j}\); Building-based \(P_b = P_z\,\frac{w_b}{\sum_{b' \in z} w_{b'}}\); integers by largest remainder per zone; Pycnophylactic \(v_i \leftarrow (1-\lambda)\,v_i + \lambda\,\bar v_i\); \(v_i \leftarrow v_i + \bigl(P_z - \sum_{j \in z} v_j\bigr)/n_z\); \(v_i \ge 0\); rescale to \(P_z\); Dasymetric-pycnophylactic as pycnophylactic, with cells \(m_i = 0\) fixed at 0 and left out of the means and corrections.

Inputs each method needs: binary and the hybrid a mask source (buildings, built-up or land cover); multi-class a land-cover raster; continuous a built-up raster or a population prior; building-based a building layer. Validation zones compares every method with finer polygons of known counts; self runs the aggregate-up self-validation.

Metrics, with \(e_u = \hat y_u - y_u\) (estimate minus observed count) over \(n\) units: \(\mathrm{RMSE} = \sqrt{\sum_u e_u^2 / n}\); \(\mathrm{MAE} = \sum_u |e_u| / n\); \(\mathrm{bias} = \sum_u e_u / n\); MAPE and MdAPE, the mean and median of \(100\,|e_u| / y_u\) (percent), over \(y_u > 0\) only, the excluded count is reported; \(\text{CV-RMSE} = \mathrm{RMSE} / \bar y\); \(R^2 = 1 - \sum_u e_u^2 \big/ \sum_u (y_u - \bar y)^2\); Pearson \(r\); total absolute error \(\mathrm{TAE} = \sum_u |e_u|\); misallocated share \(\mathrm{TAE} / (2 \sum_u y_u)\), the share of people placed in the wrong unit. Undefined metrics are NULL. best_in lists the metrics a method is best in (lowest error, highest \(R^2\) and \(r\), smallest \(|\mathrm{bias}|\)).

ParameterDescriptionTypeDefault
ZONESSource zones (census polygons)vector layer
KEY_FIELDZone key field (empty: feature id)field (optional)
METHODSMethods; options: Areal weighting | Binary dasymetric | Multi-class dasymetric | Continuous ancillary | Building-based | Pycnophylactic | Dasymetric-pycnophylacticchoiceAreal weighting, Building-based
BUILDINGSBuilding footprintsvector layer (optional)
WEIGHTBuilding weight; options: Count (1 per building) | Footprint area | Floor area (footprint \(\times\) floors) | Volume (footprint \(\times\) height) | A field (e.g. dwellings)choiceFloor area (footprint \(\times\) floors)
HEIGHT_FIELDHeight field (m)field (optional)
FLOORS_FIELDFloors fieldfield (optional)
WEIGHT_FIELDWeight field (weight = a field)field (optional)
STOREYStorey height \(h_s\) (m), floors \(F = \max\bigl(1, \lfloor H / h_s + \tfrac12 \rfloor\bigr)\)number (advanced)3.0
DEFAULT_FLOORSFloors when unknown (0: zone median of known floors, else 1)number (advanced)0.0
SPLITZone of a building; options: Zone of the point on surface | Split by overlap areachoice (advanced)Zone of the point on surface
FILTERBuilding filter expression (empty: all)expression (optional, advanced)
MIN_AREAMinimum footprint area (\(\mathrm{m^2}\))number (advanced)20.0
BUILTUPBuilt-up raster (GHS-BUILT-S/V or local)raster layer (optional)
BUILTUP_KINDBuilt-up raster values; options: Count per cell (GHS-BUILT-S/V, summed) | Share or density (averaged)choice (advanced)Count per cell (GHS-BUILT-S/V, summed)
PRIORPopulation prior (GHS-POP, WorldPop or local)raster layer (optional)
LANDCOVERLand-cover raster (WorldCover or local)raster layer (optional)
CLASS_WEIGHTSLand-cover class table (class, relative density)table (optional, advanced)WorldCover default table
CLASS_MODEMulti-class densities; options: Intelligent dasymetric mapping (sampled densities) | Regression (NNLS) | Fixed relative densities (class table)choice (advanced)Intelligent dasymetric mapping (sampled densities)
IDM_THRESHOLDIDM: minimum class share \(\theta\) of a sampled zonenumber (advanced)0.8
IDM_MIN_ZONESIDM: minimum sampled zones per class \(N_{\min}\)number (advanced)3
MASK_SOURCEBinary and hybrid mask from; options: Buildings present | Built-up raster above the threshold | Land-cover class weight above the thresholdchoice (advanced)Buildings present
MASK_THRESHOLDMask threshold \(t\)number (advanced)0.0
BETA_BUILTUPContinuous: exponent \(\beta\) of the built-up layernumber (advanced)1.0
BETA_PRIORContinuous: exponent \(\beta\) of the population priornumber (advanced)1.0
USE_MASKContinuous: multiply by the maskyes/no (advanced)False
ITERATIONSPycnophylactic: maximum iterationsnumber (advanced)500
TOLERANCEPycnophylactic: tolerance \(\tau\)number (advanced)0.0001
RELAXPycnophylactic: relaxation \(\lambda\)number (advanced)0.5
BOUNDARYPycnophylactic: boundary; options: Zero outside the study area (Tobler) | Free (mirrored edge)choice (advanced)Zero outside the study area (Tobler)
CELLCell size (m)number100.0
SUPERSAMPLESupersampling \(s\) per cell side (zone fractions)number (advanced)4
WORKING_CRSWorking CRS (empty: UTM or LAEA by the extent rule)CRS (optional, advanced)
COUNT_FIELDSCount fieldsfield
TARGETSTarget polygons (optional)vector layer (optional)
TARGETS_OUTTarget polygons with estimatesvector output (optional)
VALIDATIONAccuracy assessment; options: None | Validation zones with known counts | Aggregate-up self-validationchoiceNone
VALIDATION_ZONESValidation zones (known counts)vector layer (optional)
VALIDATION_FIELDValidation count fieldfield (optional)
BLOCKSelf-validation block side (m, 0: automatic)number (advanced)0.0
DTYPEGeoTIFF data type; options: Float32 | Float64choice (advanced)Float32
OUTPUT_FOLDERFolder for the GeoTIFFsfolder output
BUILDINGS_OUTBuildings with estimatesvector output (optional)
ERRORS_OUTError layervector output (optional)
METRICS_OUTAccuracy metricsvector output (optional)
RUN_TABLERun checks per methodvector output (optional)
REPORTHTML reportfile output (optional)

Outputs: TARGETS_OUT Target polygons with estimates; OUTPUT_FOLDER Folder for the GeoTIFFs; BUILDINGS_OUT Buildings with estimates; ERRORS_OUT Error layer; METRICS_OUT Accuracy metrics; RUN_TABLE Run checks per method; REPORT HTML report; SURFACES Surfaces written; BEST_RMSE Lowest RMSE; WORKING_CRS_USED Working CRS.

Demo city with planted truth zero2dasymetric:demo_city

Group: Study.

A deterministic synthetic city of \(6 \times 6\,\mathrm{km}\) in UTM 35N, far from the projection origin, for learning the tools and checking them: nine 2 km districts with a population count (the source zones), thirty-six 1 km neighbourhoods with the true count pop_true (validation zones), about six thousand building footprints with type, height and floors (people live only in residential buildings, in proportion to floor area times a smooth radial gradient), a built-up surface raster, a noisy population prior and a 20 m land-cover raster with WorldCover codes. The counts are the planted truth summed per zone, so every method can be scored. Suggested building filter: "type" = 'residential'.

ParameterDescriptionTypeDefault
SEEDRandom seednumber (advanced)7
RASTER_FOLDERFolder for the demo rastersfolder output
DISTRICTSDistricts (source zones)vector output
NEIGHBOURHOODSNeighbourhoods (validation zones)vector output
BUILDINGSBuildingsvector output

Outputs: RASTER_FOLDER Folder for the demo rasters; DISTRICTS Districts (source zones); NEIGHBOURHOODS Neighbourhoods (validation zones); BUILDINGS Buildings; BUILTUP Built-up surface (\(\mathrm{m^2}\) per cell); PRIOR Population prior; LANDCOVER Land cover (WorldCover codes); TOTAL Total population.

Working grid and zone fractions zero2dasymetric:zone_raster

Group: Zones and grid.

Builds the equal-area working grid of a study and rasterises the source zones on it with supersampling: every cell gets the share \(f_{iz} = n_{iz} / s^2\) of its area inside each zone (\(s \times s\) sub-cells per cell, block-counted). Every method of the plugin allocates over these (cell, zone) pairs, so this is the grid the other algorithms use with the same cell size and CRS.

Outputs: the majority zone raster (zone index + 1 of the zone that covers most of a cell when the zones cover at least half of it; nodata elsewhere), the coverage raster (share of each cell inside any zone), the working CRS with the reason it was chosen, and the rasterised-area error \(\bigl|\sum_z \sum_i f_{iz}\,a - \sum_z A_z\bigr| \big/ \sum_z A_z\). Zones smaller than one sub-cell are placed at their point on surface and counted.

CRS rule: the UTM zone when the extent lies within \(3.5^\circ\) of its central meridian, otherwise Lambert azimuthal equal-area on the extent centre.

ParameterDescriptionTypeDefault
ZONESSource zones (census polygons)vector layer
COUNT_FIELDCount fieldfield
KEY_FIELDZone key field (empty: feature id)field (optional)
CELLCell size (m)number100.0
SUPERSAMPLESupersampling \(s\) per cell side (zone fractions)number (advanced)4
WORKING_CRSWorking CRS (empty: UTM or LAEA by the extent rule)CRS (optional, advanced)
ZONE_INDEXMajority zone (index + 1)raster output
COVERAGEZone coverage shareraster output

Outputs: ZONE_INDEX Majority zone (index + 1); COVERAGE Zone coverage share; WORKING_CRS_USED Working CRS; CRS_REASON Why this CRS; ZONE_COUNT Zones; CELLS Grid cells; AREA_ERROR Rasterised area error (share); PLACED_AT_POINT Zones placed at their point on surface.

Areal weighting zero2dasymetric:areal_weighting

Group: Disaggregation methods.

Spread each zone's count evenly over its area (baseline).

Formula: \(x_{iz} = P_z\,\frac{f_{iz}\,a}{\sum_j f_{jz}\,a}\). \(P_z\) is the count of source zone \(z\), \(f_{iz}\) the share of cell \(i\) inside \(z\) (supersampled), \(a\) the cell area. Every zone total is kept exactly; a zone with no ancillary weight falls back to areal weighting and is reported.

The baseline every other method is compared with: no ancillary data.

The working grid is equal-area: the UTM zone when the zones fit inside one, otherwise a Lambert azimuthal equal-area projection on the zone centre (or the CRS you choose). The output GeoTIFF holds people per cell; cells outside every zone are nodata.

ParameterDescriptionTypeDefault
ZONESSource zones (census polygons)vector layer
COUNT_FIELDCount fieldfield
KEY_FIELDZone key field (empty: feature id)field (optional)
CELLCell size (m)number100.0
SUPERSAMPLESupersampling \(s\) per cell side (zone fractions)number (advanced)4
WORKING_CRSWorking CRS (empty: UTM or LAEA by the extent rule)CRS (optional, advanced)
TARGETSTarget polygons (optional)vector layer (optional)
TARGETS_OUTTarget polygons with estimatesvector output (optional)
OUTPUTPopulation surface (people per cell)raster output
DTYPEGeoTIFF data type; options: Float32 | Float64choice (advanced)Float32

Outputs: TARGETS_OUT Target polygons with estimates; OUTPUT Population surface (people per cell); TOTAL Total count on the surface; MASS_ERROR_MAX Largest relative zone mass error; FALLBACK_ZONES Zones that fell back to areal weighting; FALLBACK_PEOPLE People placed by the fallback; INHABITED_CELLS Inhabited cells; WORKING_CRS_USED Working CRS; LOG Run log.

Binary dasymetric zero2dasymetric:binary_dasymetric

Group: Disaggregation methods.

Spread each zone's count evenly over its inhabited cells only.

Formula: \(x_{iz} = P_z\,\frac{f_{iz}\,m_i}{\sum_j f_{jz}\,m_j},\ m_i \in \{0, 1\}\). \(P_z\) is the count of source zone \(z\), \(f_{iz}\) the share of cell \(i\) inside \(z\) (supersampled), \(a\) the cell area. Every zone total is kept exactly; a zone with no ancillary weight falls back to areal weighting and is reported.

Inhabited mask \(m_i\): cells whose summed eligible-building weight is above the threshold (with threshold 0: cells holding an eligible building), cells whose built-up value is above the threshold, or cells whose land-cover weight \(\sum_c \varphi_{ic}\,\omega_c\) (\(\omega_c\) from the class table) is above the threshold.

The working grid is equal-area: the UTM zone when the zones fit inside one, otherwise a Lambert azimuthal equal-area projection on the zone centre (or the CRS you choose). The output GeoTIFF holds people per cell; cells outside every zone are nodata.

ParameterDescriptionTypeDefault
ZONESSource zones (census polygons)vector layer
COUNT_FIELDCount fieldfield
KEY_FIELDZone key field (empty: feature id)field (optional)
MASK_SOURCEInhabited mask from; options: Buildings present | Built-up raster above the threshold | Land-cover class weight above the thresholdchoiceBuildings present
MASK_THRESHOLDMask threshold \(t\) (value above it = inhabited)number0.0
BUILDINGSBuilding footprintsvector layer (optional)
FILTERBuilding filter expression (empty: all)expression (optional, advanced)
MIN_AREAMinimum footprint area (\(\mathrm{m^2}\))number (advanced)20.0
BUILTUPBuilt-up raster (GHS-BUILT-S/V or local)raster layer (optional)
LANDCOVERLand-cover raster (WorldCover or local)raster layer (optional)
CLASS_WEIGHTSLand-cover class table (class, relative density)table (optional, advanced)WorldCover default table
CELLCell size (m)number100.0
SUPERSAMPLESupersampling \(s\) per cell side (zone fractions)number (advanced)4
WORKING_CRSWorking CRS (empty: UTM or LAEA by the extent rule)CRS (optional, advanced)
TARGETSTarget polygons (optional)vector layer (optional)
TARGETS_OUTTarget polygons with estimatesvector output (optional)
OUTPUTPopulation surface (people per cell)raster output
DTYPEGeoTIFF data type; options: Float32 | Float64choice (advanced)Float32

Outputs: TARGETS_OUT Target polygons with estimates; OUTPUT Population surface (people per cell); TOTAL Total count on the surface; MASS_ERROR_MAX Largest relative zone mass error; FALLBACK_ZONES Zones that fell back to areal weighting; FALLBACK_PEOPLE People placed by the fallback; INHABITED_CELLS Inhabited cells; WORKING_CRS_USED Working CRS; LOG Run log.

Multi-class dasymetric (fixed, IDM, regression) zero2dasymetric:multiclass_dasymetric

Group: Disaggregation methods.

Weight cells by land-cover class densities (fixed, intelligent sampling or regression).

Formula: \(w_i = \sum_c \varphi_{ic}\,d_c\); IDM: \(d_c = \sum_{z \in S_c} P_z \big/ \sum_{z \in S_c} A_z\); regression: \(P_z = \sum_c d_c\,A_{zc}\) (NNLS); \(x_{iz} = P_z\,\frac{f_{iz}\,w_i}{\sum_j f_{jz}\,w_j}\). \(P_z\) is the count of source zone \(z\), \(f_{iz}\) the share of cell \(i\) inside \(z\) (supersampled), \(a\) the cell area. Every zone total is kept exactly; a zone with no ancillary weight falls back to areal weighting and is reported.

Class fractions \(\varphi_{ic}\) come from the land-cover raster (supersampled, not the majority class). Intelligent dasymetric mapping: \(d_c = \sum_{z \in S_c} P_z \big/ \sum_{z \in S_c} A_z\) over the set \(S_c\) of source zones whose share of class \(c\), \(A_{zc} / A_z\), is at least the IDM threshold \(\theta\); classes with fewer sampled zones than the minimum get their density from the NNLS regression on the remaining counts; classes with weight \(\omega_c = 0\) in the class table stay at 0. Regression: \(P_z = \sum_c d_c\,A_{zc}\), no intercept, non-negative least squares. Fixed: the class table values \(\omega_c\) are the relative densities. The class density table output lists \(d_c\) in people per \(\mathrm{km^2}\) and where each value came from.

The working grid is equal-area: the UTM zone when the zones fit inside one, otherwise a Lambert azimuthal equal-area projection on the zone centre (or the CRS you choose). The output GeoTIFF holds people per cell; cells outside every zone are nodata.

ParameterDescriptionTypeDefault
ZONESSource zones (census polygons)vector layer
COUNT_FIELDCount fieldfield
KEY_FIELDZone key field (empty: feature id)field (optional)
LANDCOVERLand-cover raster (WorldCover or local)raster layer
MODEClass densities; options: Intelligent dasymetric mapping (sampled densities) | Regression (NNLS) | Fixed relative densities (class table)choiceIntelligent dasymetric mapping (sampled densities)
CLASS_WEIGHTSLand-cover class table (class, relative density)table (optional, advanced)WorldCover default table
IDM_THRESHOLDIDM: minimum class share \(\theta\) of a sampled zonenumber (advanced)0.8
IDM_MIN_ZONESIDM: minimum sampled zones per class \(N_{\min}\)number (advanced)3
DENSITIESClass densitiesvector output (optional)
CELLCell size (m)number100.0
SUPERSAMPLESupersampling \(s\) per cell side (zone fractions)number (advanced)4
WORKING_CRSWorking CRS (empty: UTM or LAEA by the extent rule)CRS (optional, advanced)
TARGETSTarget polygons (optional)vector layer (optional)
TARGETS_OUTTarget polygons with estimatesvector output (optional)
OUTPUTPopulation surface (people per cell)raster output
DTYPEGeoTIFF data type; options: Float32 | Float64choice (advanced)Float32

Outputs: DENSITIES Class densities; TARGETS_OUT Target polygons with estimates; OUTPUT Population surface (people per cell); TOTAL Total count on the surface; MASS_ERROR_MAX Largest relative zone mass error; FALLBACK_ZONES Zones that fell back to areal weighting; FALLBACK_PEOPLE People placed by the fallback; INHABITED_CELLS Inhabited cells; WORKING_CRS_USED Working CRS; LOG Run log.

Continuous ancillary weights zero2dasymetric:continuous_dasymetric

Group: Disaggregation methods.

Weight cells by built-up surface/volume or a population prior, rescaled to the census.

Formula: \(w_i = \prod_k \bigl(q_{ik} / \bar q_k\bigr)^{\beta_k}\); \(x_{iz} = P_z\,\frac{f_{iz}\,w_i}{\sum_j f_{jz}\,w_j}\). \(P_z\) is the count of source zone \(z\), \(f_{iz}\) the share of cell \(i\) inside \(z\) (supersampled), \(a\) the cell area. Every zone total is kept exactly; a zone with no ancillary weight falls back to areal weighting and is reported.

Each layer \(q_k\) (built-up surface or volume, a population prior such as GHS-POP or WorldPop, or any local raster) is warped onto the working grid (summed for counts, averaged for shares), divided by the mean \(\bar q_k\) of its positive cells and raised to its exponent \(\beta_k\). With a population prior as the only layer and \(\beta = 1\) this is the census-constrained rescaling of top-down gridded population products. Optionally the weight is multiplied by the inhabited mask.

Inhabited mask \(m_i\): cells whose summed eligible-building weight is above the threshold (with threshold 0: cells holding an eligible building), cells whose built-up value is above the threshold, or cells whose land-cover weight \(\sum_c \varphi_{ic}\,\omega_c\) (\(\omega_c\) from the class table) is above the threshold.

The working grid is equal-area: the UTM zone when the zones fit inside one, otherwise a Lambert azimuthal equal-area projection on the zone centre (or the CRS you choose). The output GeoTIFF holds people per cell; cells outside every zone are nodata.

ParameterDescriptionTypeDefault
ZONESSource zones (census polygons)vector layer
COUNT_FIELDCount fieldfield
KEY_FIELDZone key field (empty: feature id)field (optional)
BUILTUPBuilt-up raster (GHS-BUILT-S/V or local)raster layer (optional)
BUILTUP_KINDBuilt-up raster values; options: Count per cell (GHS-BUILT-S/V, summed) | Share or density (averaged)choice (advanced)Count per cell (GHS-BUILT-S/V, summed)
BETA_BUILTUPExponent \(\beta\) of the built-up layernumber1.0
PRIORPopulation prior (GHS-POP, WorldPop or local)raster layer (optional)
BETA_PRIORExponent \(\beta\) of the population priornumber1.0
USE_MASKMultiply by the inhabited maskyes/no (advanced)False
MASK_SOURCEInhabited mask from; options: Buildings present | Built-up raster above the threshold | Land-cover class weight above the thresholdchoice (advanced)Built-up raster above the threshold
MASK_THRESHOLDMask threshold \(t\)number (advanced)0.0
CELLCell size (m)number100.0
SUPERSAMPLESupersampling \(s\) per cell side (zone fractions)number (advanced)4
WORKING_CRSWorking CRS (empty: UTM or LAEA by the extent rule)CRS (optional, advanced)
TARGETSTarget polygons (optional)vector layer (optional)
TARGETS_OUTTarget polygons with estimatesvector output (optional)
OUTPUTPopulation surface (people per cell)raster output
DTYPEGeoTIFF data type; options: Float32 | Float64choice (advanced)Float32

Outputs: TARGETS_OUT Target polygons with estimates; OUTPUT Population surface (people per cell); TOTAL Total count on the surface; MASS_ERROR_MAX Largest relative zone mass error; FALLBACK_ZONES Zones that fell back to areal weighting; FALLBACK_PEOPLE People placed by the fallback; INHABITED_CELLS Inhabited cells; WORKING_CRS_USED Working CRS; LOG Run log.

Pycnophylactic interpolation (Tobler, dasymetric hybrid) zero2dasymetric:pycnophylactic

Group: Disaggregation methods.

The smoothest non-negative surface that keeps every zone total (Tobler).

Formula: \(v_i \leftarrow (1-\lambda)\,v_i + \lambda\,\bar v_i\); \(v_i \leftarrow v_i + \bigl(P_z - \sum_{j \in z} v_j\bigr)/n_z\); \(v_i \ge 0\); rescale to \(P_z\). \(P_z\) is the count of source zone \(z\), \(f_{iz}\) the share of cell \(i\) inside \(z\) (supersampled), \(a\) the cell area. Every zone total is kept exactly; a zone with no ancillary weight falls back to areal weighting and is reported.

Starts from areal weighting on the majority-zone raster and iterates: the mean of the four neighbours (outside the study area 0 for the zero boundary, mirrored for the free boundary), relaxation \(v_i \leftarrow (1 - \lambda)\,v_i + \lambda\,\bar v_i\), a per-zone additive correction, clamping at 0 and a per-zone rescale to \(P_z\), until \(\max_i |\Delta v_i| < \tau\,\bar v\) or the iteration limit. Volume is kept at every iteration. With Restrict to inhabited cells it becomes the dasymetric-pycnophylactic hybrid of Kim and Yao (2010): masked cells stay at exactly 0 and are left out of the neighbour means and zone corrections.

Inhabited mask \(m_i\): cells whose summed eligible-building weight is above the threshold (with threshold 0: cells holding an eligible building), cells whose built-up value is above the threshold, or cells whose land-cover weight \(\sum_c \varphi_{ic}\,\omega_c\) (\(\omega_c\) from the class table) is above the threshold.

ParameterDescriptionTypeDefault
ZONESSource zones (census polygons)vector layer
COUNT_FIELDCount fieldfield
KEY_FIELDZone key field (empty: feature id)field (optional)
ITERATIONSMaximum iterationsnumber500
TOLERANCETolerance \(\tau\) (share of the mean value)number (advanced)0.0001
RELAXRelaxation \(\lambda\)number (advanced)0.5
BOUNDARYBoundary condition; options: Zero outside the study area (Tobler) | Free (mirrored edge)choiceZero outside the study area (Tobler)
HYBRIDRestrict to inhabited cells (dasymetric-pycnophylactic)yes/noFalse
MASK_SOURCEInhabited mask from (hybrid only); options: Buildings present | Built-up raster above the threshold | Land-cover class weight above the thresholdchoiceBuildings present
MASK_THRESHOLDMask threshold \(t\) (value above it = inhabited)number0.0
BUILDINGSBuilding footprintsvector layer (optional)
FILTERBuilding filter expression (empty: all)expression (optional, advanced)
MIN_AREAMinimum footprint area (\(\mathrm{m^2}\))number (advanced)20.0
BUILTUPBuilt-up raster (hybrid mask)raster layer (optional)
LANDCOVERLand-cover raster (hybrid mask)raster layer (optional)
CLASS_WEIGHTSLand-cover class table (class, relative density)table (optional, advanced)WorldCover default table
CELLCell size (m)number100.0
SUPERSAMPLESupersampling \(s\) per cell side (zone fractions)number (advanced)4
WORKING_CRSWorking CRS (empty: UTM or LAEA by the extent rule)CRS (optional, advanced)
TARGETSTarget polygons (optional)vector layer (optional)
TARGETS_OUTTarget polygons with estimatesvector output (optional)
OUTPUTPopulation surface (people per cell)raster output
DTYPEGeoTIFF data type; options: Float32 | Float64choice (advanced)Float32

Outputs: ITERATIONS_USED Iterations; CONVERGED Converged (1) or stopped at the limit (0); TARGETS_OUT Target polygons with estimates; OUTPUT Population surface (people per cell); TOTAL Total count on the surface; MASS_ERROR_MAX Largest relative zone mass error; FALLBACK_ZONES Zones that fell back to areal weighting; FALLBACK_PEOPLE People placed by the fallback; INHABITED_CELLS Inhabited cells; WORKING_CRS_USED Working CRS; LOG Run log.

Building-based allocation zero2dasymetric:building_allocation

Group: Disaggregation methods.

Split each zone's count over its buildings by count, footprint, floor area, volume or a field.

Formula: \(P_b = P_z\,\frac{w_b}{\sum_{b' \in z} w_{b'}}\); integers by largest remainder per zone. \(P_z\) is the count of source zone \(z\), \(f_{iz}\) the share of cell \(i\) inside \(z\) (supersampled), \(a\) the cell area. Every zone total is kept exactly; a zone with no ancillary weight falls back to areal weighting and is reported.

Each eligible building gets the weight \(w_b = 1\) (count), its footprint \(A_b\), its floor area \(A_b \times F_b\), its volume \(A_b \times H_b\) (\(H_b\) from the height field, else \(F_b\,h_s\)) or a field (e.g. dwellings); the filter expression and minimum area drop sheds, garages and non-residential buildings. A building belongs to the zone holding its point on surface, or is split by overlap area. Floors from a height field: \(F_b = \max\bigl(1, \lfloor H_b / h_s + \tfrac12 \rfloor\bigr)\), \(h_s\) the storey height. Unknown floors take the zone median of known floors (or a fixed value).

Output fields (a contract shared with 02GreenRule and 02NoiseLab): src_key, w_<mode>, <field>_est (float) and <field>_int (largest remainder integers whose zone sum is \(\operatorname{round}(P_z)\)). Ineligible buildings carry NULL estimates; zones without an eligible building are reported (no building receives them). The layer is in the working CRS of the zones.

ParameterDescriptionTypeDefault
ZONESSource zones (census polygons)vector layer
COUNT_FIELDSCount fieldsfield
KEY_FIELDZone key field (empty: feature id)field (optional)
BUILDINGSBuilding footprintsvector layer
WEIGHTBuilding weight; options: Count (1 per building) | Footprint area | Floor area (footprint \(\times\) floors) | Volume (footprint \(\times\) height) | A field (e.g. dwellings)choiceFloor area (footprint \(\times\) floors)
HEIGHT_FIELDHeight field (m)field (optional)
FLOORS_FIELDFloors fieldfield (optional)
WEIGHT_FIELDWeight field (weight = a field)field (optional)
STOREYStorey height \(h_s\) (m), floors \(F = \max\bigl(1, \lfloor H / h_s + \tfrac12 \rfloor\bigr)\)number (advanced)3.0
DEFAULT_FLOORSFloors when unknown (0: zone median of known floors, else 1)number (advanced)0.0
SPLITZone of a building; options: Zone of the point on surface | Split by overlap areachoice (advanced)Zone of the point on surface
FILTERBuilding filter expression (empty: all)expression (optional, advanced)
MIN_AREAMinimum footprint area (\(\mathrm{m^2}\))number (advanced)20.0
OUTPUTBuildings with estimatesvector output

Outputs: OUTPUT Buildings with estimates; ELIGIBLE Eligible buildings; FALLBACK_ZONES Zones without an eligible building; FALLBACK_PEOPLE People in those zones; MASS_ERROR_MAX Largest relative zone mass error; TOTAL Sum of the float estimates (first field).

Population surface to polygons zero2dasymetric:surface_to_polygons

Group: Aggregation.

Sums a population surface (people per cell) over target polygons: \(\hat P_t = \sum_i f_{it}\,s_i\), with \(f_{it}\) the share of cell \(i\) inside polygon \(t\) and \(s_i\) the surface value from the same supersampled rasterisation the methods use, so a polygon that cuts a cell receives the share of the cell's count equal to the share of the cell it covers (uniform density inside a cell). Nodata cells add nothing; a polygon with no finite cell gets NULL, never 0. Polygons smaller than one sub-cell are placed at their point on surface. The output is a copy of the targets (their CRS and fields) plus the estimate field.

ParameterDescriptionTypeDefault
SURFACEPopulation surface (people per cell)raster layer
TARGETSTarget polygonsvector layer
FIELD_NAMEEstimate field nametextpop_est
SUPERSAMPLESupersampling \(s\) per cell sidenumber (advanced)4
OUTPUTTargets with estimatesvector output

Outputs: OUTPUT Targets with estimates; TOTAL Sum over the targets.

Building values to a grid zero2dasymetric:buildings_to_grid

Group: Aggregation.

Sums a numeric building field (for example population_est from Building-based allocation) per cell of each building's point on surface, on an equal-area grid of the chosen cell size over the building extent (UTM or LAEA by the extent rule, or the CRS you choose). Cells without a building hold 0; NULL values are skipped. The grid origin snaps to multiples of the cell size, so grids of the same CRS and cell size line up with the other algorithms.

ParameterDescriptionTypeDefault
BUILDINGSBuildingsvector layer
VALUE_FIELDValue fieldfield
CELLCell size (m)number100.0
SUPERSAMPLESupersampling \(s\) per cell side (zone fractions)number (advanced)4
WORKING_CRSWorking CRS (empty: UTM or LAEA by the extent rule)CRS (optional, advanced)
OUTPUTGrid of summed valuesraster output
DTYPEGeoTIFF data type; options: Float32 | Float64choice (advanced)Float32

Outputs: OUTPUT Grid of summed values; TOTAL Sum on the grid.

Accuracy against known counts zero2dasymetric:accuracy_metrics

Group: Accuracy.

Compares one or more estimate fields with an observed count field on the same polygons (for example validation neighbourhoods carrying their census count and the estimates of several methods). The metrics table holds one row per estimate field; the error layer is a copy of the polygons with obs, est_<m>, err_<m> \(= \hat y_u - y_u\) and ape_<m> \(= 100\,|\hat y_u - y_u| / y_u\) (percent, NULL where \(y_u \le 0\)).

Metrics, with \(e_u = \hat y_u - y_u\) (estimate minus observed count) over \(n\) units: \(\mathrm{RMSE} = \sqrt{\sum_u e_u^2 / n}\); \(\mathrm{MAE} = \sum_u |e_u| / n\); \(\mathrm{bias} = \sum_u e_u / n\); MAPE and MdAPE, the mean and median of \(100\,|e_u| / y_u\) (percent), over \(y_u > 0\) only, the excluded count is reported; \(\text{CV-RMSE} = \mathrm{RMSE} / \bar y\); \(R^2 = 1 - \sum_u e_u^2 \big/ \sum_u (y_u - \bar y)^2\); Pearson \(r\); total absolute error \(\mathrm{TAE} = \sum_u |e_u|\); misallocated share \(\mathrm{TAE} / (2 \sum_u y_u)\), the share of people placed in the wrong unit. Undefined metrics are NULL. best_in lists the metrics a method is best in (lowest error, highest \(R^2\) and \(r\), smallest \(|\mathrm{bias}|\)).

ParameterDescriptionTypeDefault
INPUTPolygons with observed and estimated countsvector layer
OBS_FIELDObserved count fieldfield
EST_FIELDSEstimate fieldsfield
METRICSAccuracy metricsvector output
ERRORSError layervector output (optional)

Outputs: METRICS Accuracy metrics; ERRORS Error layer; BEST_RMSE Lowest RMSE.

Aggregate-up self-validation zero2dasymetric:self_validation

Group: Accuracy.

Accuracy with a single level of data: the source zones are merged into deterministic square-block groups (block side \(L = 2\sqrt{\operatorname{median}_z A_z}\) by default, about four zones per group, the block grid starting at the top-left of the zones), every chosen method disaggregates the group totals with the same ancillary data, and the estimates are compared with the original zone counts. Groups holding a single zone carry no information and are left out (reported).

Metrics, with \(e_u = \hat y_u - y_u\) (estimate minus observed count) over \(n\) units: \(\mathrm{RMSE} = \sqrt{\sum_u e_u^2 / n}\); \(\mathrm{MAE} = \sum_u |e_u| / n\); \(\mathrm{bias} = \sum_u e_u / n\); MAPE and MdAPE, the mean and median of \(100\,|e_u| / y_u\) (percent), over \(y_u > 0\) only, the excluded count is reported; \(\text{CV-RMSE} = \mathrm{RMSE} / \bar y\); \(R^2 = 1 - \sum_u e_u^2 \big/ \sum_u (y_u - \bar y)^2\); Pearson \(r\); total absolute error \(\mathrm{TAE} = \sum_u |e_u|\); misallocated share \(\mathrm{TAE} / (2 \sum_u y_u)\), the share of people placed in the wrong unit. Undefined metrics are NULL. best_in lists the metrics a method is best in (lowest error, highest \(R^2\) and \(r\), smallest \(|\mathrm{bias}|\)).

ParameterDescriptionTypeDefault
ZONESSource zones (census polygons)vector layer
COUNT_FIELDCount fieldfield
KEY_FIELDZone key field (empty: feature id)field (optional)
METHODSMethods; options: Areal weighting | Binary dasymetric | Multi-class dasymetric | Continuous ancillary | Building-based | Pycnophylactic | Dasymetric-pycnophylacticchoiceAreal weighting, Building-based
BUILDINGSBuilding footprintsvector layer (optional)
WEIGHTBuilding weight; options: Count (1 per building) | Footprint area | Floor area (footprint \(\times\) floors) | Volume (footprint \(\times\) height) | A field (e.g. dwellings)choiceFloor area (footprint \(\times\) floors)
HEIGHT_FIELDHeight field (m)field (optional)
FLOORS_FIELDFloors fieldfield (optional)
WEIGHT_FIELDWeight field (weight = a field)field (optional)
STOREYStorey height \(h_s\) (m), floors \(F = \max\bigl(1, \lfloor H / h_s + \tfrac12 \rfloor\bigr)\)number (advanced)3.0
DEFAULT_FLOORSFloors when unknown (0: zone median of known floors, else 1)number (advanced)0.0
SPLITZone of a building; options: Zone of the point on surface | Split by overlap areachoice (advanced)Zone of the point on surface
FILTERBuilding filter expression (empty: all)expression (optional, advanced)
MIN_AREAMinimum footprint area (\(\mathrm{m^2}\))number (advanced)20.0
BUILTUPBuilt-up raster (GHS-BUILT-S/V or local)raster layer (optional)
BUILTUP_KINDBuilt-up raster values; options: Count per cell (GHS-BUILT-S/V, summed) | Share or density (averaged)choice (advanced)Count per cell (GHS-BUILT-S/V, summed)
PRIORPopulation prior (GHS-POP, WorldPop or local)raster layer (optional)
LANDCOVERLand-cover raster (WorldCover or local)raster layer (optional)
CLASS_WEIGHTSLand-cover class table (class, relative density)table (optional, advanced)WorldCover default table
CLASS_MODEMulti-class densities; options: Intelligent dasymetric mapping (sampled densities) | Regression (NNLS) | Fixed relative densities (class table)choice (advanced)Intelligent dasymetric mapping (sampled densities)
IDM_THRESHOLDIDM: minimum class share \(\theta\) of a sampled zonenumber (advanced)0.8
IDM_MIN_ZONESIDM: minimum sampled zones per class \(N_{\min}\)number (advanced)3
MASK_SOURCEBinary and hybrid mask from; options: Buildings present | Built-up raster above the threshold | Land-cover class weight above the thresholdchoice (advanced)Buildings present
MASK_THRESHOLDMask threshold \(t\)number (advanced)0.0
BETA_BUILTUPContinuous: exponent \(\beta\) of the built-up layernumber (advanced)1.0
BETA_PRIORContinuous: exponent \(\beta\) of the population priornumber (advanced)1.0
USE_MASKContinuous: multiply by the maskyes/no (advanced)False
ITERATIONSPycnophylactic: maximum iterationsnumber (advanced)500
TOLERANCEPycnophylactic: tolerance \(\tau\)number (advanced)0.0001
RELAXPycnophylactic: relaxation \(\lambda\)number (advanced)0.5
BOUNDARYPycnophylactic: boundary; options: Zero outside the study area (Tobler) | Free (mirrored edge)choice (advanced)Zero outside the study area (Tobler)
CELLCell size (m)number100.0
SUPERSAMPLESupersampling \(s\) per cell side (zone fractions)number (advanced)4
WORKING_CRSWorking CRS (empty: UTM or LAEA by the extent rule)CRS (optional, advanced)
BLOCKBlock side \(L\) (m, 0: \(L = 2\sqrt{\operatorname{median}_z A_z}\))number0.0
METRICSAccuracy metricsvector output

Outputs: METRICS Accuracy metrics; BEST_RMSE Lowest RMSE; LEVEL Validation level.

Agreement with a population prior zero2dasymetric:prior_agreement

Group: Accuracy.

Sums a gridded population product (GHS-POP, WorldPop or a local raster, warped onto the working grid with sum resampling so totals are kept) over every census zone with the zone fractions \(f_{iz}\) and divides it by the census count: \(\rho_z = \sum_i f_{iz}\,p_i / P_z\), with \(p_i\) the prior in cell \(i\). Reports the median ratio, the interquartile range \(Q_3 - Q_1\) and the share of zones with \(|\rho_z - 1| \le 0.2\) (within \(\pm 20\,\%\)). This is agreement between two estimates, not accuracy. Zones with a NULL or zero count get a NULL ratio.

ParameterDescriptionTypeDefault
ZONESSource zones (census polygons)vector layer
COUNT_FIELDCount fieldfield
KEY_FIELDZone key field (empty: feature id)field (optional)
PRIORPopulation prior (GHS-POP, WorldPop or local)raster layer
CELLCell size (m)number100.0
SUPERSAMPLESupersampling \(s\) per cell side (zone fractions)number (advanced)4
WORKING_CRSWorking CRS (empty: UTM or LAEA by the extent rule)CRS (optional, advanced)
OUTPUTZones with the prior ratiovector output

Outputs: OUTPUT Zones with the prior ratio; MEDIAN Median ratio; Q1 First quartile; Q3 Third quartile; WITHIN_20 Share of zones within 20 percent; N Zones compared; PRIOR_TOTAL Prior total over the zones; CENSUS_TOTAL Census total.

Fetch GHSL, WorldPop or WorldCover zero2dasymetric:fetch_population_data

Group: Data.

Downloads the tiles of a population, built-up or land-cover product that cover an extent into a cache folder through the QGIS network settings (proxy and authentication), and returns the raster (a VRT mosaic when several tiles are needed). Run it first with Only report the size to see the URLs and the download size (HTTP HEAD) before anything is downloaded. Cached files are reused; GHSL ocean tiles that do not exist (HTTP 404) are listed and read as zero. WorldPop needs the ISO3 country code (e.g. TUR) and serves no byte ranges, so its file is always downloaded whole. Licence and citation are returned for the report.

ParameterDescriptionTypeDefault
PRODUCTProduct; options: GHS-POP R2023A (100 m) | GHS-BUILT-S R2023A (100 m) | GHS-BUILT-V R2023A (100 m) | WorldPop R2025A constrained (100 m) | ESA WorldCover 10 mchoiceGHS-POP R2023A (100 m)
YEARYear (GHSL epochs 1975-2030 every 5 years; WorldPop 2015-2030; WorldCover 2020 or 2021)number2020
EXTENTStudy extentextent
ISO3Country (ISO3, WorldPop only)text (optional)
CACHECache folderfolder (optional)system temp folder / zero2dasymetric_cache
PLAN_ONLYOnly report the size (no download)yes/noFalse
STREAMRead GHSL and WorldCover remotely (GDAL /vsicurl/) instead of downloadingyes/no (advanced)False

Outputs: OUTPUT Raster; BYTES Bytes downloaded; PLANNED_BYTES Bytes still to download; URLS URLs; MISSING Missing tiles; LICENCE Licence; CITATION Citation.

9. Output layers and fields

OutputContent
Surface GeoTIFF <method>.tif (<field>_<method>.tif for further count fields)people per cell on the working grid; nodata outside every zone
Buildingsthe building's own fields plus src_key (zone key), w_<mode> (weight), <field>_est (float) and <field>_int (largest-remainder integer) per count field; NULL for ineligible buildings. The _est and _int names are shared with 02GreenRule and 02NoiseLab, which read this layer directly.
Targetsa copy of the target polygons with <method>_est (one count field) or <field>_<method>_est (several); building-based estimates sum the buildings whose point on surface lies in each polygon. With one count field also area_km2 (planar, working CRS; added when absent) and <method>_dens (people per \(\mathrm{km^2}\))
Method spread GeoTIFF method_spread_cv.tifper cell, the coefficient of variation \(\mathrm{CV}_i = \sigma_i / \mu_i\), with \(\mu_i = \frac{1}{M} \sum_k s_{ik}\) and \(\sigma_i = \sqrt{\frac{1}{M} \sum_k (s_{ik} - \mu_i)^2}\) over the \(M\) method surfaces \(s_{ik}\) of the first count field: where it is high, the estimate depends on the method choice. Defined where every surface is defined and \(\mu_i > 0\), nodata elsewhere; written with every run of two or more methods and by GeoTIFF per method
Error layerobs, est_<m>, err_<m> \(= \hat y_u - y_u\), ape_<m> \(= 100\,|\hat y_u - y_u| / y_u\) (percent, NULL where \(y_u \le 0\))
Accuracy metrics tableone row per method: n, obs_total, est_total, rmse, mae, bias, mape, mdape, cv_rmse, r2, pearson_r, tae, misallocated_share, best_in (equations (14) to (18))
Run tableone row per count field and method: mass_error_max \(= \max_z |\sum_i x_{iz} - P_z| / P_z\), fallback_zones, fallback_people, inhabited_cells, iterations, total
HTML reportinputs, working CRS and reason, parameters, per-method checks, class densities, the comparison table, the method spread summary, charts as inline SVG, every formula (typeset with KaTeX, numbered as in this manual), data source, licence and reference, and the run log

10. Worked example: the demo city

The demo city is deterministic: \(6 \times 6\,\mathrm{km}\) in UTM 35N around (500 000, 4 250 000), far from the projection origin. People live only in residential buildings, in proportion to floor area times a smooth radial gradient; the zone counts are that planted truth summed per zone, so every method can be scored.

In the dock

  1. Open the lab from the toolbar. On Zones, press Load demo city. The badge reads UTM 35N; the summary shows 9 zones, 143 313 people, \(4.00\,\mathrm{km^2}\) median zone area and 3 844 cells of 100 m (\(62 \times 62\) with one cell of padding).
  2. On Ancillary, the demo buildings, built-up raster, prior and land cover are filled in, the building filter is "type" = 'residential' and the height and floors fields are picked up by name (floors are used before height): 5 157 of 5 942 buildings are eligible.
  3. On Method, choose all seven methods and press Run disaggregation (about a second on a desktop machine). Every method reports a mass error of the order of \(10^{-15}\); pycnophylactic converges in about 450 iterations.
  4. On Accuracy, choose Validation zones with the neighbourhoods and pop_true, and press Assess.
  5. On Report, export the HTML report, the GeoTIFFs, the GeoPackage and the CSV.

In Processing

  1. Run Demo city with planted truth: it writes the three layers and the three rasters.
  2. Run Population disaggregation lab (whole study) with the districts, count field population, key dist_id, all seven methods, the buildings with the filter above and floors field floors, the three rasters, validation Validation zones with known counts on the neighbourhoods with pop_true, and a report path.

Result

RMSE against the 36 neighbourhoods (people per neighbourhood; mean count about 3 980):

MethodRMSE
Building-based (floor area, residential filter)117
Continuous (built-up and prior)351
Pycnophylactic461
Dasymetric-pycnophylactic (building mask)470
Multi-class (IDM)877
Binary (building mask)1 251
Areal weighting1 732

Aggregate-up self-validation of areal weighting and building-based allocation on the districts alone gives RMSE 22 700 and 1 738: the same ranking without any finer data. Prior agreement: the median ratio of the noisy prior to the census is 0.99 over the nine districts.

The demo numbers are reproduced by the plugin's test suites on every release (smoke_truth, smoke_pipeline, smoke_processing).

11. Limitations

12. References

  1. Eicher, C. L., Brewer, C. A. (2001). Dasymetric mapping and areal interpolation: implementation and evaluation. Cartography and Geographic Information Science 28(2), 125-138.
  2. Fisher, P. F., Langford, M. (1995). Modelling the errors in areal interpolation between zonal systems by Monte Carlo simulation. Environment and Planning A 27(2), 211-224.
  3. GDAL/OGR contributors (2025). GDAL/OGR Geospatial Data Abstraction software Library. Open Source Geospatial Foundation. https://gdal.org
  4. Goodchild, M. F., Lam, N. S.-N. (1980). Areal interpolation: a variant of the traditional spatial problem. Geo-Processing 1, 297-312.
  5. Kim, H., Yao, X. (2010). Pycnophylactic interpolation revisited: integration with the dasymetric-mapping method. International Journal of Remote Sensing 31(21), 5657-5671.
  6. Langford, M., Maguire, D. J., Unwin, D. J. (1991). The areal interpolation problem: estimating population using remote sensing in a GIS framework. In Masser, I., Blakemore, M. (eds), Handling Geographical Information, 55-77. Longman.
  7. Langford, M., Unwin, D. J. (1994). Generating and mapping population density surfaces within a geographical information system. The Cartographic Journal 31(1), 21-26.
  8. Lawson, C. L., Hanson, R. J. (1974). Solving Least Squares Problems. Prentice-Hall, Englewood Cliffs.
  9. Leyk, S., Gaughan, A. E., Adamo, S. B., de Sherbinin, A., Balk, D., Freire, S., Rose, A., Stevens, F. R., Blankespoor, B., Frye, C., Comenetz, J., Sorichetta, A., MacManus, K., Pistolesi, L., Levy, M., Tatem, A. J., Pesaresi, M. (2019). The spatial allocation of population: a review of large-scale gridded population data products and their fitness for use. Earth System Science Data 11, 1385-1409.
  10. Lwin, K., Murayama, Y. (2009). A GIS approach to estimation of building population for micro-spatial analysis. Transactions in GIS 13(4), 401-414.
  11. Mennis, J. (2003). Generating surface models of population using dasymetric mapping. The Professional Geographer 55(1), 31-42.
  12. Mennis, J., Hultgren, T. (2006). Intelligent dasymetric mapping and its application to areal interpolation. Cartography and Geographic Information Science 33(3), 179-194.
  13. QGIS Development Team (2026). QGIS Geographic Information System. Open Source Geospatial Foundation Project. https://qgis.org
  14. Snyder, J. P. (1987). Map Projections - A Working Manual. U.S. Geological Survey Professional Paper 1395. U.S. Government Printing Office, Washington.
  15. Stevens, F. R., Gaughan, A. E., Linard, C., Tatem, A. J. (2015). Disaggregating census data for population mapping using random forests with remotely-sensed and ancillary data. PLoS ONE 10(2), e0107042.
  16. Tobler, W. R. (1979). Smooth pycnophylactic interpolation for geographical regions. Journal of the American Statistical Association 74(367), 519-530.
  17. Willmott, C. J., Matsuura, K. (2005). Advantages of the mean absolute error (MAE) over the root mean square error (RMSE) in assessing average model performance. Climate Research 30, 79-82.
  18. Yuan, Y., Smith, R. M., Limp, W. F. (1997). Remodeling census population with spatial information from Landsat TM imagery. Computers, Environment and Urban Systems 21(3-4), 245-258.
  19. Zandbergen, P. A., Ignizio, D. A. (2010). Comparison of dasymetric mapping techniques for small-area population estimates. Cartography and Geographic Information Science 37(3), 199-214.

Data

  1. Schiavina, M., Freire, S., MacManus, K. (2023). GHS-POP R2023A - GHS population grid multitemporal (1975-2030). European Commission, Joint Research Centre (JRC). doi:10.2905/2FF68A52-5B5B-4A22-8F40-C41DA8332CFE.
  2. Pesaresi, M. (2023). GHS-BUILT-S R2023A - GHS built-up surface grid, derived from Sentinel-2 composite and Landsat, multitemporal (1975-2030). European Commission, JRC. doi:10.2905/9F06F36F-4B11-47EC-ABB0-4F8B7B1D72EA.
  3. Pesaresi, M., Politis, P. (2023). GHS-BUILT-V R2023A - GHS built-up volume grids derived from joint assessment of Sentinel-2, Landsat, and global DEM data, multitemporal (1975-2030). European Commission, JRC. doi:10.2905/AB2F107A-03CD-47A3-85E5-139D8EC63283.
  4. Bondarenko, M. et al. (2025). Constrained estimates of 2015-2030 total number of people per grid square, R2025A version v1. WorldPop, University of Southampton. doi:10.5258/SOTON/WP00839.
  5. Zanaga, D. et al. (2022). ESA WorldCover 10 m 2021 v200. Zenodo. doi:10.5281/zenodo.7254221.

13. Citation, licence, links

If you use 02Dasymetric in published work, cite it (see CITATION.cff) together with the method papers and the data products you used:

Eminoğlu, Y. (2026). 02Dasymetric - Population Disaggregation Lab (version 0.1.2) [QGIS plugin]. https://gitlab.com/geophilo1/zero2dasymetric. https://doi.org/10.5281/zenodo.24263646. The DOI 10.5281/zenodo.24263646 always resolves to the latest version; version 0.1.2 has DOI https://doi.org/10.5281/zenodo.24263647.

Licence: GPL-2.0-or-later. Copyright (C) 2026 Yusuf Eminoğlu (Geophilo).