From d8edf8c8b72d3bc132782631dd4410bcb1cdebc4 Mon Sep 17 00:00:00 2001 From: Svetlana Titova Date: Thu, 19 Dec 2024 10:44:19 -0800 Subject: [PATCH] Updates after Mandy's review (Thank you, Mandy!) (#13) * Updates after Mandy's review (Thank you, Mandy!) --- .../software-migration-creation-vector.rst | 19 ++++++------ docs/emod/software-migration-vector.rst | 31 +++++++------------ 2 files changed, 22 insertions(+), 28 deletions(-) diff --git a/docs/emod/software-migration-creation-vector.rst b/docs/emod/software-migration-creation-vector.rst index 7a5f30a..26d2af9 100644 --- a/docs/emod/software-migration-creation-vector.rst +++ b/docs/emod/software-migration-creation-vector.rst @@ -3,8 +3,8 @@ How to create vector migration files ==================================== You can create the JSON metadata and binary migration files needed by |EMOD_s| to run simulations -from CSV data using Python script below. You can assign the same probability of migration to -each vector in a node or you can assign different migration rates based on gender or genetics of the vector. +from CSV data using the Python script below. You can assign the same probability of migration to +each vector in a :term:`node` or you can assign different migration rates based on gender or genetics of the vector. #. Run the 'convert_csv_to_bin_vector_migration.py' script using the format below:: @@ -89,17 +89,17 @@ Actual csv: .. literalinclude:: ../csv/vector-migration-by-sex-input.csv +.. _migration_vector_genetics: Different rates depending on genetics of the vector --------------------------------------------------- Header (required): FromNodeID, ToNodeID, [], arrays denoting Allele_Combinations -Allele_Combinations example: [["a1", "a1"], ["b1", "b1"]] or [["X1","Y2"]] or [["*", "a0"], ["X1", "Y1"]] -Due to use of commas in headers, it is best to use Excel to create them (or look at a sample text csv). -This is to support VECTOR_MIGRATION_BY_GENETICS. Headers are required for this csv file. +Allele_Combinations: [["a1", "a1"], ["b1", "b1"]] or [["X1","Y2"]] or [["*", "a0"], ["X1", "Y1"]] +Due to use of commas in headers, it is best to use Excel to create the csv input files. The first (empty, []) array is used as a "default rate" if the vector's genetics doesn't match any of the Allele_Combinations. The other column headers denote the rate that the vector will travel at if it matches the -Allele_Combination listed. Vectors are checked against Allele_Combinations from most-specific, to least-specific, +Allele_Combinations listed. Vectors are checked against Allele_Combinations from most-specific, to least-specific, regardless of the order in the csv file. Allele_Combinations can, but don't have to, include sex-alleles. Without specified sex-alleles, any vector that matches the alleles regardless of sex will travel at that rate. Use '*' as a wildcard if the second allele does not matter and can be matched with anything. @@ -152,9 +152,10 @@ JSON metadata file ================== The metadata file is a JSON-formatted file that includes a metadata section and a node offsets -section. The **Metadata** section contains a JSON object with parameters that help |EMOD_s| interpret the migration -binary file. The users are encouraged to add their own parameters to the section to remind themselves about the source, -reason, purpose of the binary file and the data it contains. Non-required parameters are ignored. +section. The **Metadata** section contains a :term:`JSON (JavaScript Object Notation)` with parameters that help +|EMOD_s| interpret the migration binary file. You are encouraged to add your own parameters to the section to remind +your selves about the source, reason, and purpose of the binary file and the data it contains. Non-required parameters +are ignored. Vector Migration Metadata File Parameters diff --git a/docs/emod/software-migration-vector.rst b/docs/emod/software-migration-vector.rst index 6aee3eb..79e25a9 100644 --- a/docs/emod/software-migration-vector.rst +++ b/docs/emod/software-migration-vector.rst @@ -1,41 +1,34 @@ ================= -Vector Migration +Vector migration ================= -Vector migration file describes the rate of migration of vectors *out* of a geographic :term:`node` -analogously to human migration (see :doc:`software-migration` for more information), the vector +The vector migration file describes the rate of migration of vectors *out* of a geographic :term:`node` +analogously to human migration (see :doc:`software-migration` for more information). The vector model does not support migration by age and age-based migration in the migration file will cause an -error. Vector migration does support migration by gender as well as migration based on genetics (see below). +error, but does support migration by vector gender as well as migration based on genetics (see below). Vector migration is one way, such that each trip made by a vector is independent of previous trips made by the vector. Note: If default geography is used (the configuration parameter **Enable_Demographics_Builtin** is set to 1, and **Default_Geography_Initial_Node_Population** and **Default_Geography_Torus_Size** are configured), -vector migration will be built internally and vectors will automatically migrate. It is a known issue, -please see https://github.com/InstituteforDiseaseModeling/EMOD/issues/43 +vector migration will be built internally and vectors will automatically migrate. -Vectors do not have a "MigrationType" as each species use only one file for all their migration needs. +Vectors do not have a "MigrationType" as each species uses only one file for all their migration needs. -Each vector species has its own **Vector_Migration_Filename**, if it is left as an empty string, no +Each vector species has its own **Vector_Migration_Filename**; if it is left as an empty string, no migration will happen for that species. The **Vector_Migration_Modifier_Equation** and its parameters can influence female vector migration to particular nodes over others, while **x_Vector_Migration** is -a multiplier affects the migration rates for both genders. See :doc:`parameter-configuration` for more +a multiplier that affects the migration rates for both genders. See :doc:`parameter-configuration` for more information on the parameters governing vector migration. + Vector Migration Using Genetics =============================== -Vectors have a type of migration not available to humans set with "GenderDataType": VECTOR_MIGRATION_BY_GENETICS in the +Vectors have a type of migration not available to humans set with **GenderDataType** = VECTOR_MIGRATION_BY_GENETICS in the migration metadata file (usually a .bin.json file). -The way this migration works is that you can define a migration rate for each defined Allele_Combination. -Allele_Combinations example: [ [], [["a1", "a1"], ["b1", "b1"]], [["X1","Y2"]], [["*", "a0"], ["X1", "Y1"]]] -The first (empty, []) array is used as a "default rate" if the vector's genetics doesn't match any of the -Allele_Combinations. The other column Allele_Combinations will be associated with the rate that the vector will use -if it matches with that Allele_Combination. Vectors are checked against Allele_Combinations from most-specific, -to least-specific, regardless of the order in the Allele_Combinations parameter. Allele_Combinations can, -but don't have to, include sex-alleles. Without specified sex-alleles, any vector that matches the alleles regardless -of sex will travel at that rate. Please see Vector Migration File creation for more information. +For information, see :ref:`migration_vector_genetics`. Vector Migration Files @@ -43,7 +36,7 @@ Vector Migration Files The Binary file structure for the vector migration files is the same as it is for human files. The Allele_Combinations array, when present for vector VECTOR_MIGRATION_BY_GENETICS, is used in the same capacity as -AgesYears array would be to maintain the same structure of the file. Please see migration file creation +AgesYears array would be to maintain the same structure of the file. Please see :doc:`software-migration-creation` for more details. .. toctree::