Welcome to MESS’s documentation!¶

Installation¶

MESS requires Python >= 3.5. Binaries can be downloaded with conda or built with pip.

Method 1: Install pre-built binary from conda¶

Download anaconda or miniconda.
(Optional) create a separate conda environment to install into:

conda create -n mess-env
source activate mess-env

Install:

conda install -c mess -c conda-forge -c anaconda -c r mess
#conda install mess openblas dendropy -c mess -c conda-forge -c anaconda

See venv to install into a virtual environment.

Intro CLI Tutorial¶

MESS - Massive Eco-Evolutionary Synthesis Simulations

Example CLI:

## Create a new params file and populate with default values
MESS -n neutral_model

<edit params-neutral_model.txt>

## Generate 10000 simulations
MESS -p params-neutral_model.txt -s 10000

## Validate format of empirical data from a directory (proper formatting will be checked)
MESS -i empirical_dir

## Perform abc model selection (competition model also previously simulated)
## Both neutral and competition models should have been simulated for a similar
## number of replicates, MESS will check for this.
MESS -i empirical_dir --abc params-neutral_model.txt params-competition_model.txt

## Perform random forest model selection (competition model also previously simulated)
MESS -i empirical_dir --RF params-neutral_model.txt params-competition_model.txt

## Estimate parameters of empirical data for a given model
## TODO: Figure out how to specify which parameters to estimate?
MESS -i empirical_dir -p params-neutral_model.txt --estimate_params

## Generate fancy plots through time for a given model. This will
## only run one realization and create several animated gifs <slow>
MESS -p params-neutral_model.txt --fancy-plots

The code is on github

Intro API Tutorial¶

MESS - Massive Eco-Evolutionary Synthesis Simulations

Example API:

import MESS

## A mess region contains all universal parameters of the model, metacommunity
## information, and one or more local communities that can be connected
data = MESS.Region("my_first_sim")

## Define the metacommunity model
data.set_metacommunity("logseries")

## Add local communities to the region
loc1 = data.add_local_community("Island1", J=5000, c=0.01)
loc2 = data.add_local_community("Island2", J=1000, c=0.05)

## Define the potentially asymmetric migration matrix
## Migration matrix should be square with dimension equal to # of local communities and,
## diagonal elements == 0
data.migration_matrix([[0, 0.05], [0.05, 0]])

## Run the simulation for x number of generations
data.simulate(nsims=100000)
## Alternatively simulate until some proportion of equilibrium is reached
results = data.simulate(lambda=0.7)

print(results)

Inference Procedure¶

The code is on github

ML Inference¶

Supported Ensemble Methods¶

MESS currently supports three different scikit-learn ensemble methods for classification and parameter estimation:

RandomForest (rf):
GradientBoosting (gb):
AdaBoost (ab):

Model Selection¶

Parameter Estimation¶

Community Assembly Parameters¶

The parameters contained in a params file affect the behavior of various parts of the forward-time and backward-time assembly process. The defaults that we chose are fairly reasonable values as as starting point, however, you will always need to modify at least a few of them (for example, to indicate the location of your data), and often times you will want to modify many of the parameters.

Below is an explanation of each parameter setting, the eco-evolutionary process that it affects, and example entries for the parameter into a params.txt file.

simulation_name¶

The simulation name is used as the prefix for all output files. It should be a unique identifier for this particular set of simulations, meaning the set of parameters you are using for the current data set. When I run multiple related simulations I usually use names indicating the specific parameter combinations (e.g., filtering_nospeciation, J5000_neutral).

Example: New community simulations are created with the -n options to MESS:

## create a new assembly named J1000_neutral
$ MESS -n J1000_neutral

project_dir¶

A project directory can be used to group together multiple related simulations. A new directory will be created at the given path if it does not already exist. A good name for project_dir will generally be the name of the community/system being studied. The project dir path should generally not be changed after simulations/analysis are initiated, unless the entire directory is moved to a different location/machine.

Example entries into params.txt:

/home/watdo/MESS/galapagos         ## [1] create/use project dir called galapagos
galapagos                          ## [1] create/use project dir called galapagos in cwd (./)

generations¶

This parameter specifies the amount of time to run forward-time simulations. It can be specified in a number of different ways, but overall time can be considered either in terms of Wright-Fisher (WF) generations or in terms of Lambda. For WF generations you should specify an integer value (or a range of integer values) which will run the forward-time process for WF * J / 2 time-steps (where a time-step is one birth/death/colonization/speciation event). For Lambda you may select either an exact Lambda value (a real value between 0 and 1 exclusive), or you can set generations equal to 0, which will draw random Lambda values between 0 and 1 for each simulation.

Example entries into params.txt:

0                   ## [2] [generations]: Sample random Lambda values for each simulation
100                 ## [2] [generations]: Run each simulation for 100 WF generations
50-100              ## [2] [generations]: Sample uniform between 50-100 WF generations for each simulation

community_assembly_model¶

With this parameter you may specify a neutral or non-neutral scenario for the forward time process. There are currently three different options for this parameter: neutral, filtering, or competition. The neutral case indicates full ecological equivalence of all species, so all individuals have an equal probability of death at each time-step. In the filtering and competition models survival probability is contingent on proximity of species trait values to the environmental optimum, or distance from the local trait mean, respectively. You may also use the wildcard * here and MESS will randomly sample one community assembly model for each simulation.

Example entries into params.txt:

neutral             ## [3] [community_assembly_model]: Select the neutral process forward-time
filtering           ## [3] [community_assembly_model]: Select the environmental filtering process
*                   ## [3] [community_assembly_model]: Randomly choose one of the community assembly models

speciation_model¶

Specify a speciation process in the local community. If none then no speciation happens locally. If point_mutation then one individual will instantaneously speciate at rate speciation_prob for each forward-time step. If random_fission then one lineage will randomly split into two lineages at rate speciation_prob with the new lineage receiving n = U~(1, local species abundance) individuals, and the parent lineage receiving 1 - n individuals. protracted will specify a model of protracted speciation, but this is as yet unimplemented.

Example entries into params.txt:

none                ## [4] [speciation_model]: No speciation in the local community
point_mutation      ## [4] [speciation_model]: Point mutation specation process

mutation_rate¶

Specify the mutation rate for backward-time coalescent simulation of genetic variation. This rate is the per base, per generation probability of a mutation under an infinite sites model.

Example entries into params.txt:

2.2e-08             ## [5] [mutation_rate]: Mutation rate scaled per base per generation

alpha¶

Scaling factor for transforming number of demes to number of individuals. alpha can be specified as either a single integer value or as a range of values.

Example entries to params.txt file:

2000                ## [6] [alpha]: Abundance/Ne scaling factor
1000-10000          ## [6] [alpha]: Abundance/Ne scaling factor

sequence_length¶

Length of the sequence to simulate in the backward-time process under an infinite sites model. This value should be specified based on the length of the region sequenced for the observed community data in bp.

Example entries to params.txt file:

570                 ## [7] [sequence_length]: Length in bases of the sequence to simulate

S_m¶

S_m specifies the total number of species to simulate in the metacommunity. Larger values will result in more singletons in the local community and reduced rates of multiple-colonization.

Example entries to params.txt file:

500                 ## [0] [S_m]: Number of species in the regional pool
100-1000            ## [0] [S_m]: Number of species in the regional pool