Data and code from: Foundations for digital twins: Spatially disaggregated synthetic populations of refugee and IDP settlements

Refugee and internally displaced people (IDPs) settlements are highly dynamic, with rapid changes to demographic and geographical structures. Knowledge of the population size, disaggregated by demographic attributes, is essential to informing humanitarian programming and settlement planning by humanitarian organisations. However, access to such data, when formal censuses of settlements have not been conducted creates a significant barrier. In this paper, we present a methodological framework for estimating settlement censuses by combining globally available satellite imagery with aggregate national census data from the population's country of origin generate a spatially disaggregated synthetic population of the settlement. The creation of such synthetic populations serves as a foundational layer for Digital Twins and simulation models, enabling: the integration of these disparate datasets at different levels of granularity; and provides decision-makers with a spatially disaggregated dynamic model of the population to inform response requirements before sending humanitarian teams into new settlements and later informing survey methods, or used to simulate scenarios for policy planning and public health responses among others. We develop and validate our framework in three diverse contexts: the Zaatari and Cox's Bazar settlements in Jordan and Bangladesh; and the Kismayo displacement settlement in Somalia. # Replication Code and Data: Spatially Disaggregated Synthetic Population Generation This repository contains the mock data, models, and complete 4-script computational pipeline to reproduce the methodology and results presented in our paper. The framework extracts shelter footprints from satellite imagery and generates a highly granular, spatially disaggregated synthetic population for non-monitored settlements. All processing scripts are bundled in the compressed archive: `RSOS-251315_code_data.zip`. ## Data Sources and Availability * **Refugee Camp Imagery:** The actual imagery used in the paper consists of four high-resolution satellite images of Zaatari camp (taken Sept 2013, Nov 2013, Jan 2014, and Mar 2014 from Maxar's WorldView-2 and GeoEye-1), obtained via the United Nations. * **Imagery Substitutes:** Due to commercial licensing and political sensitivities, the original high-resolution imagery cannot be published in this repository. Instead, lower-resolution substitutes from Google Earth are used for illustrative purposes in the paper. * **Census and Demographic Data:** * **Zaatari Refugee Camp:** Demographic data for the camp were synthesized from official UNHCR (United Nations High Commissioner for Refugees) situational reports. These baseline figures serve as the foundational population parameters for the analysis presented in the paper. The original source documentation can be accessed via the UNHCR Data Portal: * [data.unhcr.org](data.unhcr.org) * [data.unhcr.org](data.unhcr.org) * [data.unhcr.org](data.unhcr.org) * [data.unhcr.org](data.unhcr.org) * **Country of Origin (Syria):** Real-world demographic data for the country of origin were retrieved from [populationpyramid.net](populationpyramid.net) to support the age-stratified modeling utilized in this research. * **Mock Gender and Age Distribution Data** ([syria_population_dist.csv], [zaatari_population_dist.csv]) Description: To allow users to test the code and reproduce the age-stratified modeling used in this research, these two mock (synthetic) datasets have been provided. They structurally mimic the real age-gender pyramids. Scripts that call these files: [3.Synthetic_Population_Dist.ipynb] Variables: ``` [upper_age]: Numeric variable representing the upper limit of the specific age bracket (e.g., indicating the end of a cohort like [0,5) or [5-10)). [M]: Numeric variable representing the mock population count of males in that specific age bracket. [F]: Numeric variable representing the mock population count of females in that specific age bracket. [m_par]: Numeric variable representing the proportion of males relative to the total population used for modeling. [f_par]: Numeric variable representing the proportion of females relative to the total population used for modeling. ``` ## Pipeline Architecture and Code Structure The methodology is divided into two distinct phases: Geospatial Processing (using Meta's SAM2) and Demographic Generation. The pipeline is designed to be executed sequentially using the following four scripts: ### Phase 1: Geospatial Processing (Camp Area Extraction) > **⚠️ Important Data Requirement:** Because the original high-resolution satellite imagery cannot be shared due to commercial licensing, **users must provide their own high-resolution satellite imagery datasets** to execute the training and inference steps in this phase. * `1.fine-tune_SAM2.ipynb` * **Description:** Contains the training pipeline to fine-tune the SAM2 machine learning model on satellite imagery to detect semi-permanent shelter structures. * `2.inference_and_combine_tiles.ipynb` * **Description:** Runs inference over the settlement imagery to delineate individual shelter footprints, combine image tiles, and calculate the total estimated camp area and population magnitude. ### Phase 2: Demographic Generation (Synthetic Population) * `3.Synthetic_Population_Dist.ipynb` * **Description:** Takes the total population estimate and the national baseline census data (mock data provided) to generate the aggregate age-sex distribution. This script handles the population rescaling (e.g., correcting for the "youth bulge" using the ~0.7 factor). *Note: Base demographic parameters (national age-sex distribution, total population) can be easily modified at the top of this script to adapt to new crises.* * `4.Household_Distributor.py` * **Description:** The final distribution model. It takes the rescaled population and dynamically allocates individuals into explicit family/household units (assuming a 1:1 shelter-to-household ratio). *Note: Target parameters such as mean household size, children per family, and the mother-firstborn age gap can be defined by the user here.* ## How to Run Execute the scripts in numerical order (1 through 4). Researchers wishing to bypass the heavy SAM2 geospatial processing can skip directly to scripts 3 and 4 by inputting their own total population and demographic proxy estimates.