emod_api.migration.migration module

class emod_api.migration.migration.Layer

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

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

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

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: pathlib.Path, metafile: Optional[pathlib.Path] = None, value_limit: int = 100)

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: pathlib.Path, metafile: Optional[pathlib.Path] = None)

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)

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)

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) → emod_api.migration.migration.Migration

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)

emod_api.migration.migration.to_csv(filename: pathlib.Path)

emod_api.migration.migration.from_csv(filename: pathlib.Path, id_ref, mig_type=None)

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