emodpy_malaria.migration.vector_migration module#

class emodpy_malaria.migration.vector_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 emodpy_malaria.migration.vector_migration.VectorMigration[source]#

Bases: object

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

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_MIGRATION = 1#
REGIONAL_MIGRATION = 3#
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 | REGIONAL

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)

emodpy_malaria.migration.vector_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.

emodpy_malaria.migration.vector_migration.examine_file(filename)[source]#
emodpy_malaria.migration.vector_migration.from_params(demographics_file_path: any | None = None, population: int = 1000000.0, num_nodes: int = 100, migration_factor: float = 1.0, fraction_rural=0.3, id_ref='IfReference', 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.

emodpy_malaria.migration.vector_migration.from_demog_and_param_gravity_webservice(demographics_file_path: str, params: str, id_ref: str, migration_type=1) → VectorMigration[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

emodpy_malaria.migration.vector_migration.from_demographics_and_gravity_params(demographics_object, gravity_params: list, filename: str | None = None)[source]#

This function takes a demographics object, creates a vector migration file based on the populations and distances of nodes and saves to be used by the sim

Parameters:

  • demographics_object – demographics object created by Demographics class (use Demographics.from_file() to load a demographics file you already have and pass in the returned object)

  • gravity_params – a list of four parameters that will affect the gravity model gravity_params[0] denoted as g[0], etc, and they are used in the following way: migration_rate = g[0] * (from_node_population^(g[1]-1)) * (to_node_population^g[2]) * (distance^g[3]) if rate >= 1, 1 is used.

  • filename – name of migration file to be created and added to the experiment, Default: vector_migration.bin

Returns:

VectorMigration object

emodpy_malaria.migration.vector_migration.to_csv()[source]#
emodpy_malaria.migration.vector_migration.from_csv(filename_path: str, id_reference: str, migration_type: str = 'LOCAL_MIGRATION', author: str | None = None)[source]#

Create migration from csv file. The file should have columns ‘from_node’ for the node ids from which vector is migrating, ‘to_node’ for the node ids that the vector is migrating to, and ‘rate’ for the migration rate.

Example:

from_node,to_node,rate
1, 4, 0.5
4, 1, 0.01
Parameters:

  • filename_path – name (if same folder) or path+name of the csv file

  • id_reference – IdReference parameter to set for the migration file, it needs to be the same as IdReference parameter in your demographics files.

  • migration_type – “LOCAL_MIGRATION” or “REGIONAL_MIGRATION” setting, “LOCAL_MIGRATION” can have 8 “to_nodes” while “REGIONAL_MIGRATION” can have 30, default is “LOCAL_MIGRATION”

  • author – optional metadata of who is the author(you) of the migration file, default - your username or empty string will be used

Returns:

Migration object to be manipulated or written out as a file using to_file() function