emod_api.migration.migration module#

class emod_api.migration.migration.Layer[source]#

Bases: dict

The Layer object represents a mapping from source node (IDs) to destination node (IDs) for a particular age, gender, age+gender combination, or all users if no age or gender dependence. Users will not generally interact directly with Layer objects.

property DatavalueCount: int#

Get (maximum) number of data values for any node in this layer

Returns:

Maximum number of data values for any node in this layer

property NodeCount: int#

Get the number of (source) nodes with rates in this layer

Returns:

Number of (source) nodes with rates in this layer

class emod_api.migration.migration.Migration[source]#

Bases: object

Represents migration data in a mapping from source node (IDs) to destination node (IDs) with rates for each pairing.

Migration data may be age dependent, gender dependent, both, or the same for all ages and genders. A migration file (along with JSON metadata) can be loaded from the static method Migration.from_file() and inspected and/or modified. Migration objects can be started from scratch with Migration(), and populated with appropriate source-dest rate data and saved to a file with the to_file() method. Given migration = Migration(), syntax is as follows:

age and gender agnostic: migration[source_id][dest_id] age dependent: migration[source_id:age] # age should be >= 0, ages > last bucket value use last bucket value gender dependent: migration[source_id:gender] # gender one of Migration.MALE or Migration.FEMALE age and gender dependent: migration[source_id:gender:age] # gender one of Migration.MALE or Migration.FEMALE

EMOD/DTK format migration files (and associated metadata files) can be written with migration.to_file(<filename>). EMOD/DTK format migration files (with associated metadata files) can be read with migration.from_file(<filename>).

SAME_FOR_BOTH_GENDERS = 0#
ONE_FOR_EACH_GENDER = 1#
LINEAR_INTERPOLATION = 0#
PIECEWISE_CONSTANT = 1#
LOCAL = 1#
AIR = 2#
REGIONAL = 3#
SEA = 4#
FAMILY = 5#
INTERVENTION = 6#
IDREF_LEGACY = 'Legacy'#
IDREF_GRUMP30ARCSEC = 'Gridded world grump30arcsec'#
IDREF_GRUMP2PT5ARCMIN = 'Gridded world grump2.5arcmin'#
IDREF_GRUMP1DEGREE = 'Gridded world grump1degree'#
MALE = 0#
FEMALE = 1#
MAX_AGE = 125#
property AgesYears: list#

List of ages - ages < first value use first bucket, ages > last value use last bucket.

property Author: str#

str: Author value for metadata for this migration datafile

property DatavalueCount: int#

int: Maximum data value count for any layer in this migration datafile

property DateCreated: datetime#

datetime: date/time stamp of this datafile

property GenderDataType: int#

int: gender data type for this datafile - SAME_FOR_BOTH_GENDERS or ONE_FOR_EACH_GENDER

property IdReference: str#

str: ID reference metadata value

property InterpolationType: int#

int: interpolation type for this migration data file - LINEAR_INTERPOLATION or PIECEWISE_CONSTANT

property MigrationType: int#

int: migration type for this migration data file - LOCAL | AIR | REGIONAL | SEA | FAMILY | INTERVENTION

property Nodes: list#
property NodeCount: int#

int: maximum number of source nodes in any layer of this migration data file

get_node_offsets(limit: int = 100) → dict[source]#
property NodeOffsets: dict#

dict: mapping from source node id to offset to destination and rate data in binary data

property Tool: str#

str: tool metadata value

to_file(binaryfile: Path, metafile: Path | None = None, value_limit: int = 100)[source]#

Write current data to given file (and .json metadata file)

Parameters:

  • binaryfile (Path) – path to output file (metadata will be written to same path with “.json” appended)

  • metafile (Path) – override standard metadata file naming

  • value_limit (int) – limit on number of destination values to write for each source node (default = 100)

Returns:

path to binary file

Return type:

(Path)

emod_api.migration.migration.from_file(binaryfile: Path, metafile: Path | None = None)[source]#

Reads migration data file from given binary (and associated JSON metadata file)

Parameters:

  • binaryfile (Path) – path to binary file (metadata file is assumed to be at same location with “.json” suffix)

  • metafile (Path) – use given metafile rather than inferring metafile name from the binary file name

Returns:

Migration object representing binary data in the given file.

emod_api.migration.migration.examine_file(filename)[source]#
emod_api.migration.migration.from_params(demographics_file_path=None, pop=1000000.0, num_nodes=100, mig_factor=1.0, frac_rural=0.3, id_ref='from_params', migration_type=1)[source]#

This function is for creating a migration file that goes with a (multinode) demographics file created from a few parameters, as opposed to one from real-world data. Note that the ‘demographics_file_path” input param is not used at this time but in future will be exploited to ensure nodes, etc., match.

emod_api.migration.migration.from_demog_and_param_gravity_webservice(demographics_file_path: str, params: str, id_ref: str, migration_type=1) → Migration[source]#

Calls a webservice (running on a GPU) to calculate the migration patterns quickly.

Parameters:

  • demographics_file_path – Path to the demographics file.

  • params – Path to the json file with parameters for gravity calculation and server url.

  • id_ref – Metadata tag that needs to match corresponding value in demographics file.

  • migration_type – Migration type.

Returns:

Migration object

emod_api.migration.migration.from_demog_and_param_gravity(demographics_file_path, gravity_params, id_ref, migration_type=1)[source]#
emod_api.migration.migration.to_csv(filename: Path)[source]#
emod_api.migration.migration.from_csv(filename: Path, id_ref, mig_type=None)[source]#

Create migration from csv file. The file should have columns ‘source’ for the source node, ‘destination’ for the destination node, and ‘rate’ for the migration rate.

Parameters:

filename – csv file

Returns:

Migration object