Emergence 1.0

Emergence
=========

Python source code for studying the simultaneous emergence of ecological patterns.

Purpose
-------

**Emergence** performs three tasks:

1. Builds and runs individual-based ecological models based on dynamics of selection, stochasticity, and energetics.

2. Quantifies and records individual-to-ecosystem level information across time steps and models.

3. Provides quantitative and graphical tools for analysis of ecological patterns and relationships.

The ODD protocol
----------------

Grimm *et al* (2006) developed a protocol known as the ODD as a standard for describing individual-based models (IBMs).
Because **Emergence** is a platform for IBMs and not simply a model, we descibe **Emergence** as close as reasonable according to the ODD.
See EmergencePrePrint.md file located in the manuscript directory.
The user should note that the ODD was not intended for describing software.

Grimm, V. *et al*. (2006) A standard protocol for describing individual-based and agent-based models. Ecological Modeling. **198,** 115-126. *not OA*


Suggested software
------------------

Emergence was developed on the Enthought Canopy Python distribution (version 1.5.5) available here: https://store.enthought.com/

Emergence implements unit testing using pytest version 2.8.1; see: http://pytest.org/latest/getting-started.html#getstarted

Emergence output can be imported into Python and R environments as dataframes.
R scripts are provided in the tools/Rcode folder.
For this reason, the R friendly user may want to install RStudio: https://www.rstudio.com/products/rstudio/download/ and/or R: https://www.r-project.org/

A free preprint version of the Emergence manuscript is generated using Pandoc version 1.15.0.6.: http://pandoc.org/installing.html

Files & Directories
-------------------

The following are general descriptions. For greater detail of the contents of various directories, see the info.md files located in each directory or the comments in the source code.

**License:** An MIT license stating the conditions under which Emergence is freely provided.

**EmergencePrePrint.md:** A markdown version of the Emergence manuscript.

**EmergencePrePrint.pdf:** A pdf version of the Emergence manuscript.
This pdf is generated with Pandoc version 1.15.0.6, using the command:

~/GitHub/Emergence/EmergencePrePrint.md --latex-engine=xelatex -o ~/GitHub/Emergence/EmergencePrePrint.pdf

Directory: results
------------------

* Sub-directory: figures -- Contains files for figures resulting from user analyses. Also contains a folder of example figures.

* Sub-directory: simulated_data -- Contains files generated by Emergence models.

* Sub-directory: movies -- Contains example animations of Emergence models.

Directory: model
----------------

* main.py: This is the primary file for running Emergence.
Once run, Emergence begins assembling and running simulation models. Output for the numbers of models run and additional cursory data are printed to the users terminal window.

* Sub-directory: spatial_functions -- Contains a file for calculating distances and examining species-area relationships.

* Sub-directory: processes -- Contains files for simulating active dispersal, consumption, disturbance, growth, immigration, basal metabolism, passive dispersal, reproduction, resource flow and resource inflow, speciation, and transitions between metabolically active and dormant physiological states.

* Sub-directory: input_output -- Contains a file (labels.py) used for modifying and importing data labels and a file (output.py) used for writing simulation data to the SimData.csv, RAD.csv, and SAR.csv files.

* Sub-directory: fluid_dynamics -- Contains code for simulating computational fluid dynamics

* Sub-directory: diversity_metrics -- Contains code for quantifying multiple aspects of local scale diversity and temporal changes in diversity.

Directory: tools
----------------

* Sub-directory: DiversityTools -- Contains code for obtaining predicted species abundance distributions. This directory contains an info.md file.

* Sub-directory: Rcode -- Contains R scipts for analysis of simulation data.

* Sub-directory: SADfits -- Contains python code for fitting species abundance distributions to simulation data

* Sub-directory: unit_tests -- Contains python code for testing metrics of diversity, spatial statistics, the operation of simulation processes (e.g., reproduction), and the writing of data to output files.


Unit tests
----------

Source code for unit testing, available in the **tools/unit_tests** directory.
The following unit testing is currently implemented on:

* Spatial statistics
* Diversity metrics
* Generation of figures and data
* Functions that simulate ecological processes