GENERATE A SET OF MODELS

PHRAPL models need to be stored in a migrationArrayobject. Technically, this object can be named whatwever you want to name it, but the structure should be as the one described here and in explore models. We recommend sticking with the name migrationArray to avoid confusion.

What is a migrationArray object?
Generating a migrationArray object

What is a migrationArray object?

A migrationArray object is a list of models that will be explored by PHRAPL and is generated by the fuction GenerateMigrationIndividuals. Models only need to be generated once for a specific number of populations, migration rates, coalescent events, and/or population sizes.

When the system of interest includes 2 or 3 groups, we recommend generating a migrationArray object with a full set of models (i.e., isolation-only, migration-only, and isolation-with-migration). Models can be filtered depending on the research question. For initial explorations, we recommend keeping the models simple (e.g., forcing symmetric migration). Then select a smaller set of models and increase the number of free parameters (e.g., fix one or a few topologies and allow asymmetric migration and different population sizes). Models can be as specific as required. See the section explore models to be more familiar with how these models are structured.

Generating a migrationArray object

Example 1: Three populations, all topologies, all scenarios of symmetric migration, same population size.

This example explains how to create a set of models for 3 population, where symmetric migration is forced and all possible topologies will be generated.

## This example generates a set of models for 3 population, where symmetric migration is forced and all possible topologies and island models will be created.

setwd("/your_working_directory/")
library(phrapl)

migrationArray<-GenerateMigrationIndividuals(
popVector=c(2,2,2),               # how many population/species/groups do you have? If you have 2, then type c(2,2) or c(3,3) [the number of individuals doesn't matter here]. In this example, there are 3 populations.
maxK=3,                           # maximum number of parameters in total (considering migration rates and coalescent events)
maxMigrationK=1,                  # maximum number of parameters that will be assigned to migration rates
maxN0K=1,                         # maximum number of parameters that will be assigned to population sizes
maxGrowthK=0,                     # maximum number of growth parameters that will be incorporated into the model set
forceSymmetricalMigration=TRUE,   # Do you want to generate a set of models with symmetric migration among all populations? (TRUE/FALSE)
forceTree=FALSE)                  # Do you want to force all population to collapse? (if TRUE only fully-resolved trees will be included in the set of models)
 
migrationArrayMap<-GenerateMigrationArrayMap(migrationArray) 
save(migrationArray,migrationArrayMap, file="MigrationArray_3Pop_4K.rda")

Example 2: Three populations, two topologies, all scenarios of asymmetric migration, same population size.

This example generates a set of models for 3 population, where asymmetric migration is allowed and two topologies are fixed.

## This example generates a set of models for 3 population, where asymmetric migration is allowed and two topologies are fixed (2 and 4).

setwd("/your_working_directory/")
library(phrapl)

migrationArray<-GenerateMigrationIndividuals(
popVector=c(2,2,2),               # how many population/species/groups do you have? If you have 2, then type c(2,2) or c(3,3) [the number of individuals doesn't matter here]. In this example, there are 3 populations.
maxK=3,                           # maximum number of parameters in total (considering migration rates and coalescence events)
maxN0K=1,                         # maximum number of parameters that will be assigned to population sizes
maxGrowthK=0,                     # maximum number of growth parameters that will be incorporated into the model set
maxMigrationK=1,                  # maximum number of parameters that will be assigned to migration rates
forceSymmetricalMigration=FALSE,  # Do you want to generate a set of model with symmetric migration among all populations? (TRUE/FALSE)
forceTree=FALSE,                  # Do you want to force all population to collapse? (if TRUE only fully-resolved trees will be included in the set of models)
parallelRep=c(2,4))               # Fix topologies 2 and 4. This option requires previous exploration of similar migrationArray objects.

migrationArrayMap<-GenerateMigrationArrayMap(migrationArray) 
save(migrationArray,migrationArrayMap, file="MigrationArray_3Pop_4K_AssymMig_forcedTree_2and4.rda")

Example 3: Three populations, one topology, one scenario of symmetric migration, and all options of a single event of population growth.

This example generates a set of models with a fixed topology and a fixed migration scenario, and includes all possible distributions of a single population growth parameter across three populations.

## This example generates a set of models with a given tree and migration scenario and all possible distributions of a single population growth parameter across three populations.

setwd("/your_working_directory/")
library(phrapl)

popVector<-c(3,3,3)
maxK=5
maxGrowthK=2
forceTree=TRUE

# Fix a tree
collapse_1<-c(1,1,0)
collapse_2<-c(2,NA,2)
collapseList<-list(collapse_1,collapse_2)

# Fix migration
migration_1<-t(array(c(
 	NA, 1, 1,
 	1, NA, 1,
	1, 1, NA),
dim=c(3,3)))

migration_2<-t(array(c(
 	NA, NA, 2,
	NA, NA, NA,
	2,  NA, NA),
dim=c(3,3)))
migrationList<-list(migration_1,migration_2)

migrationArray<-GenerateMigrationIndividuals(popVector=popVector,maxK=maxK,maxGrowthK=maxGrowthK,
 	collapseList=collapseList,migrationList=migrationList,forceTree=forceTree)