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

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

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

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.vector_migration.vector_migration.examine_file(filename)[source]
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.

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

Parameters:

  • 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

Returns:

VectorMigration object

emodpy_malaria.vector_migration.vector_migration.to_csv()[source]
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.

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