The above animations show: Left: the movements of 30 synthetic residents sampled from the area code 251400 (Wellington Central) in the early morning (between 7am and 8am). Right: Where people go to work in one day (3000 sampled synthetic citizens across Auckland region)

Syspop is a package developed to simplify and modularize the synthesis of populations, enhancing efficiency and user-friendliness. The outputs generated by Syspop are independent of any downstream applications, such as agent-based models, making them versatile inputs for various modeling needs or standalone products.

The documentation for the package can be found at SysPop Wiki. Any questions please contact: [email protected]

• Installation
• Usage
• Output
• Release (for developer)

The package can be installed via:

pip install syspop

A synthetic population can be created using:

from syspop.syspop import create as syspop_create

syspop_create(
    syn_areas = [135400, 111400, 110400],
    output_dir = "/tmp/syspop_test",
    pop_gender = pop_data["gender"],
    pop_ethnicity = pop_data["ethnicity"],
    geo_hierarchy = geog_data["hierarchy"],
    geo_location = geog_data["location"],
    geo_address = geog_data["address"],
    household = household_data["household"],
    socialeconomic = geog_data["socialeconomic"],
    work_data = work_data,
    home_to_work = commute_data["home_to_work"],
    school_data = school_data["school"],
    hospital_data = hospital_data["hospital"],
    supermarket_data = supermarket_data["supermarket"],
    restaurant_data = restaurant_data["restaurant"],
    assign_address_flag = True,
    rewrite_base_pop = False,
    use_parallel = True,
    ncpu = 8
)

Detailed descriptions of the input data for each argument can be found in Input data.

It's important to note that all arguments in the syspop.create function are optional, and their requirement depends on the specific synthetic information that needs to be generated. To understand the interdependencies between different synthetic information, refer to the documentation available here

The daily activity (diary) for the produced synthetic population can be created using the function syspop.diary:

from syspop import diary as syspop_diary
syspop_diary(output_dir="/tmp/syspop", n_cpu=1)

where output_dir refers to the directory where the synthetic population is stored (e.g., /tmp/syspop/syspop_base.parquet). The output will be stored in the directory as <output_dir>/diaries.parquet. The details of creating diaries for synthetic population can be found here

The produced syntehtic population from syspop.create can be validated using the function of syspop.validate:

from syspop.syspop import validate as syspop_validate
syspop_validate(
    output_dir=output_dir,
    pop_gender=pop_data["gender"],
    pop_ethnicity=pop_data["ethnicity"],
    household=household_data["household"],
    work_data=work_data,
    home_to_work=commute_data["home_to_work"],
)

The above codes provide validation for the produced synthetic population, which must be stored in <output_dir>/syspop_base.csv. Details for synthetic population validation can be found here.

The produced syntehtic population from syspop.create can be plotted using the function of syspop.vis:

from syspop.syspop import vis as syspop_vis
syspop_vis(
    output_dir=output_dir,
    plot_distribution=True,
    plot_travel=True,
    plot_location=True,
    travel_sample_size=250,
)

The above codes provide validation for the produced synthetic population, which must be stored in <output_dir>/syspop_base.csv. Details for synthetic population visualization can be found here.

The output from Syspop is a comprehensive table that contains the information for each synthetic individual, which can be used for any downstream analytic and modeling works. The list of attributes for each synthetic individual can be found here

The package can be released by running:

make publish

Note that before the release, it is suggested to check the latest version by make pkg_version, and then adjust the version number in setup.py accordingly.