emodpy_malaria.vector_migration.vector_migration module#

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


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


Number of (source) nodes with rates in this layer

class emodpy_malaria.vector_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>).

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)

  • 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)


path to binary file

Return type:


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

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

  • 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


Migration object representing binary data in the given file.

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

  • 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.


Migration object

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

This function takes a demographics object, creates a vector migration file based on the populations and distances of nodes, sets up the parameters for it to be used with the simulations, creates a vector migration file (and the metadata file) and adds it to the simulations via task

  • task – task object that contains all the simulation data and files. It will be used to set parameters and add vector_migration files to the simulation.

  • 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.

  • migration_type – migration_type associated with migration file, you’ll need to appropriately match up the Vector_Migration_Filename_Regional with the file that has REGIONAL_MIGRATION setting for migration_type, options are VectorMigration.REGIONAL_MIGRATION or VectorMigration.LOCAL_MIGRATION

  • filename – name of migration file to be created and added to the experiment, Default: vector_migration_(migration_type).bin


VectorMigration object

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


1, 4, 0.5
4, 1, 0.01
  • 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


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