emod_api.demographics.DemographicsGenerator module

exception emod_api.demographics.DemographicsGenerator.InvalidResolution

Bases: BaseException

Custom Exception

class emod_api.demographics.DemographicsGenerator.DemographicsType(value)

Bases: Enum

STATIC = 'static'

emod_api.demographics.DemographicsGenerator.arcsec_to_deg(arcsec: float) → float

Arc second to degrees :param arcsec: arcsecond as float

Returns:

arc second converted to degrees

emod_api.demographics.DemographicsGenerator.validate_res_in_arcsec(res_in_arcsec)

Validate that the resolution is valid :param res_in_arcsec: Resolution in arsecond. Supported values can be found in VALID_RESOLUTIONS

Returns:

None.

Raise:

KeyError: If the resolution is invalid, a key error is raised

class emod_api.demographics.DemographicsGenerator.DemographicsGenerator(nodes, concerns: emod_api.dtk_tools.demographics.DemographicsGeneratorConcern.DemographicsGeneratorConcern | List[emod_api.dtk_tools.demographics.DemographicsGeneratorConcern.DemographicsGeneratorConcern] | None = None, res_in_arcsec='custom', node_id_from_lat_long=False)

Bases: object

Generates demographics file based on population input file. The population input file is csv with structure

node_label*, lat, lon, pop*

*-ed columns are optional

set_resolution(res_in_arcsec)

The canonical way to set arcsecond/degree resolutions on a DemographicsGenerator object. Verifies everything is set properly

Parameters:

res_in_arcsec – The requested resolution. e.g. 30, 250, ‘custom’

Returns: No return value.

generate_nodes(defaults)

generate demographics file nodes

The process for generating nodes starts with looping through the loaded demographics nodes. For each node, we: 1. First determine the node’s id. If the node has a forced id set, we use that. If we are using a custom resolution, we use the index(ie 1, 2, 3…). Lastly, we build the node id from the lat and lon id of the node

2. We then start to populate the node_attributes and individual attributes for the current node. The node_attributes will have data loaded from the initial nodes fed into DemographicsGenerator. The individual attributes start off as an empty dict.

3. We next determine the birthrate for the node. If the node attributes contains a Country element, we first lookup the birthrate from the World Pop data. We then build a MortalityDistribution configuration with country specific configuration elements and add that to the individual attributes. If there is no Country element in the node attributes, we set the birth rate to the default_birth_rate. This value was set in initialization of the DemographicsGenerator to the birth rate of the specified country from the world pop data

4. We then calculate the per_node_birth_rate using get_per_node_birth_rate and then set the birth rate on the node attributes

5. We then calculate the equilibrium_age_distribution and use that to create the AgeDistribution in individual_attributes

6. We then add each new demographic node to a list to end returned at the end of the function

generate_metadata()

generate demographics file metadata

generate_demographics()

return all demographics file components in a single dictionary; a valid DTK demographics file when dumped as json

emod_api.demographics.DemographicsGenerator.from_dataframe(df, demographics_filename: str | None = None, concerns: emod_api.dtk_tools.demographics.DemographicsGeneratorConcern.DemographicsGeneratorConcern | List[emod_api.dtk_tools.demographics.DemographicsGeneratorConcern.DemographicsGeneratorConcern] | None = None, res_in_arcsec='custom', node_id_from_lat_long=True, default_population: int = 1000, load_other_columns_as_attributes=False, include_columns: List[str] | None = None, exclude_columns: List[str] | None = None, nodeid_column_name: str | None = None, latitude_column_name: str = 'lat', longitude_column_name: str = 'lon', population_column_name: str = 'pop')

Generates a demographics file from a dataframe

Parameters:

• df – pandas DataFrame containing demographics information. Must contain all the columns specified by latitude_column_name, longitude_column_name. The population_column_name is optional. If not found, we fall back to default_population

• demographics_filename – demographics file to save the demographics file too. This is optional

• concerns (Optional[DemographicsNodeGeneratorConcern]) – What DemographicsNodeGeneratorConcern should

• DefaultWorldBankEquilibriumConcern (we apply. If not specified, we use the) –

• res_in_arcsec – Resolution in Arcseconds

• node_id_from_lat_long – Determine if we should calculate the node id from the lat long. By default this is true unless you also set res_in_arcsec to CUSTOM_RESOLUTION. When not using lat/long for ids, the first fallback it to check the node for a forced id. If that is not found, we assign it an index as id

• load_other_columns_as_attributes – Load additional columns from a csv file as node attributes

• include_columns – A list of columns that should be added as node attributes from the csv file. To be used in conjunction with load_other_columns_as_attributes.

• exclude_columns – A list of columns that should be ignored as attributes when load_other_columns_as_attributes is enabled. This cannot be combined with include_columns

• default_population – Default population. Only used if population_column_name does not exist

• nodeid_column_name – Column name to load nodeid values from

• latitude_column_name – Column name to load latitude values from

• longitude_column_name – Column name to load longitude values from

• population_column_name – Column name to load population values from

Returns:

demographics file as a dictionary

emod_api.demographics.DemographicsGenerator.from_file(population_input_file: str, demographics_filename: str | None = None, concerns: emod_api.dtk_tools.demographics.DemographicsGeneratorConcern.DemographicsGeneratorConcern | List[emod_api.dtk_tools.demographics.DemographicsGeneratorConcern.DemographicsGeneratorConcern] | None = None, res_in_arcsec='custom', node_id_from_lat_long=True, default_population: int = 1000, load_other_columns_as_attributes=False, include_columns: List[str] | None = None, exclude_columns: List[str] | None = None, nodeid_column_name: str | None = None, latitude_column_name: str = 'lat', longitude_column_name: str = 'lon', population_column_name: str = 'pop')

Generates a demographics file from a CSV population

Parameters:

• population_input_file – CSV population file. Must contain all the columns specified by latitude_column_name, longitude_column_name. The population_column_name is optional. If not found, we fall back to default_population

• demographics_filename – demographics file to save the demographics file too. This is optional

• concerns (Optional[DemographicsNodeGeneratorConcern]) – What DemographicsNodeGeneratorConcern should

• DefaultWorldBankEquilibriumConcern (we apply. If not specified, we use the) –

• res_in_arcsec – Resolution in Arcseconds

• node_id_from_lat_long – Determine if we should calculate the node id from the lat long. By default this is true unless you also set res_in_arcsec to CUSTOM_RESOLUTION. When not using lat/long for ids, the first fallback it to check the node for a forced id. If that is not found, we assign it an index as id

• load_other_columns_as_attributes – Load additional columns from a csv file as node attributes

• include_columns – A list of columns that should be added as node attributes from the csv file. To be used in conjunction with load_other_columns_as_attributes.

• exclude_columns – A list of columns that should be ignored as attributes when load_other_columns_as_attributes is enabled. This cannot be combined with include_columns

• default_population – Default population. Only used if population_column_name does not exist

• nodeid_column_name – Column name to load nodeid values from

• latitude_column_name – Column name to load latitude values from

• longitude_column_name – Column name to load longitude values from

• population_column_name – Column name to load population values from

Returns:

demographics file as a dictionary